forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: r376128 [16/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/howt...
Date Thu, 09 Feb 2006 00:26:32 GMT
Propchange: forrest/site/docs_0_80/changes.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/compliance.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/compliance.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/compliance.source.xml (added)
+++ forrest/site/docs_0_80/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>pelt</code>" skin
+        validates as HTML 4.0.1
+      </p>
+      <p>
+        The "<code>tigris</code>" skin
+        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_80/compliance.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/dispatcher.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/dispatcher.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/dispatcher.source.xml (added)
+++ forrest/site/docs_0_80/dispatcher.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,118 @@
+<?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>Dispatcher (Draft - feature under development)</title>
+  </header>
+  <body>
+    <warning> The "dispatcher" is new functionality which is still in 
+      development phase. That is why it is in the "whiteboard" section of the 
+      Forrest distribution. We are working at the moment on moving this plugin
+      from the whiteboard into the core plugins. </warning>
+    <section id="introduction">
+      <title>Introduction</title>
+      <p> As stated in the <link href="site:v0.80//documentation/skins">Skin 
+        documentation </link> the aim of the Forrest skins is to provide many 
+        capabilities so that extra skins are not needed. Experience showed that 
+        many Forrest users still decided to create a new skin because the 
+        default skin did not offer the features that they wanted or they "just" 
+        needed extra content in some pages. We introduced skinconf.xml where 
+        the user could configure some features of skins but it was up to the 
+        skin to support it and did not solve the problem to add page specific 
+        extra content. That led us to develop a new concept of creating skins 
+        (we called the result "themes") which would be more easily extensible 
+        by a user. </p>
+    </section>
+    <section id="background">
+      <title>Background</title>
+      <p> The problem with the forrest skins so far has been that even if 
+        "only" the design changed (html-skeleton), we still had to write a 
+        completely new skin and implement all functionality. Another problem 
+        was that the functionality was not easily extensible by a user. We 
+        decided to support a standard regarding naming conventions for css 
+        elements. This standard has been developed on the <link href="http://www.oscom.org/events/oscom4/proposals/skins"> OSCOM 
+        website</link>, where you can find some more background information.</p>
+      <section id="nc-definition">
+        <title>Definition of naming conventions</title>
+        <p> "A naming convention is an attempt to systematize names in a field 
+          so they unambiguously convey similar information in a similar 
+          manner." <link href="http://en.wikipedia.org/wiki/Naming_conventions">wikipedia</link> 
+          </p>
+      </section>
+      <section id="leather">
+        <title>leather-dev</title>
+        <p> That led to the development of the "leather-dev" skin which 
+          established a semantic container approach for div elements. 
+          Leather-dev evolved from the "pelt" skin and almost used the same 
+          functionality (contracts). We had started to encapsulate functional 
+          code into templates, but there have been still in 4 xsl files and without 
+          any documentation what they are doing and how to use them. The 
+          problems with leather-dev was pointed out in the mail "<link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=111049344517653">status on leather-dev?</link>". The main proplem was to limit users to 
+          only one html-skeleton was way too limiting regarding design. Since 
+          we had now grouped functionality in named container we were ready to 
+          start the dispatcher (aka forrest:views).</p>
+      </section>
+    </section>
+    <section id="dispatcher">
+      <title>Dispatcher - advanced separation of concerns</title>
+      <p> The aim of the "dispatcher" concept is to provide a flexible 
+        framework for creating site and page specific layout in different 
+        formats from different content through an advanced seperation of 
+        concerns.</p>
+      <p>The dispatcher is a filter that limits the data-model to a minimum by 
+        only requesting what the strucuter (e.g. common.fv) need. This leads to 
+        a different URL handling focus - away from document centric. A document 
+        can (but do not have to) be behind a certain URL. Like said a 
+        structurer can request any given data as input not only a document and 
+        the forrest core contracts (like navigation). It may be the main 
+        enhancement in comparison to skins that this concept let you easily 
+        extend the default data models provided by forrest.</p>
+      <p>Since the dispatcher has implemented a fallback concept it makes 
+        maintenance of custom themes which are based on forrest core ones very 
+        easy and less time consuming. The principal is to override or extend 
+        only certain parts (contracts) of the core. This is based on the 
+        observation that normally only a small percentage of core skin 
+        contracts have been changed. At the same time the new plugin system 
+        emerged. Plugins are a way of extending Forrest to satisfy 
+        site-specific needs. This includes to provide plugin specific 
+        contracts.</p>
+      <section id="contracts">
+        <title>Contracts - grouped functionality</title>
+        <p>The result of the leather-dev development were grouped functionality 
+          in named container. We gave those code snippets names (based on their 
+          functionality) and called them contracts. This naming enabled us to 
+          keep the contract separate from the position code itself. Further 
+          since major parts of the code of skins never have been documentended 
+          we started to add for each contract a description and an explanation 
+          how to use this contract. The skinconf.xml gave an excellent 
+          source for this documentation effort, since it described most 
+          features of the pelt skin.</p>
+          <p>Contracts are standalone, self explaining, configurable 
+            pieces of xsl templates created out of pure maintaining reasons.</p>
+      </section>
+    </section>
+    <section id="info">
+      <title>Further information</title>
+      <p> Apache Forrest 1.0 Specification (Draft, not yet published): 
+        <code>site-author/content/xdocs/TR/2005/WD-forrest10.html</code> </p>
+      <p> See the various How-to documents about the dispatcher, starting with 
+        <link href="site:v0.80//howto/dispatcher/install">installing the 
+        dispatcher</link> and
+        <link href="site:v0.80//howto/dispatcher/quickstart">quickstart</link>
+      </p>
+    </section>
+  </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/dispatcher.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/dreams.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/dreams.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/dreams.source.xml (added)
+++ forrest/site/docs_0_80/dreams.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,246 @@
+<?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>Forrest dream list</title>
+  <subtitle>Overview</subtitle>
+ </header>
+
+ <body>
+ <section>
+  <title>Introduction</title>
+
+  <p>This is the initial attempt to give focus to the Forrest project. 
+   This summary is a loose collection of items from the forrest-dev
+   mailing list. Please add and re-arrange so that it can evolve into a
+   focus document. The <link href="site:v0.80//primer">Forrest Primer</link>
+   provides an overview.
+  </p>
+
+  <p>These are the email threads and documents that are currently being
+   summarised. Please see those documents for further detail.
+  </p>
+
+  <ul>
+   <li>
+    [RT] my Forrest dream-list
+    Date: Wed, 20 Feb 2002
+    <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101431895118349">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101431895118349</link>
+    [done]
+   </li>
+   <li>
+    README 
+    [FIXME: not yet started summarising]
+   </li>
+   <li>
+    [phases] Forrest
+    Date: Fri, 22 Feb 2002
+    <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101445744931104">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101445744931104</link>
+    [FIXME: not yet started summarising]
+   </li>
+   <li>
+    adding to the dream list
+    Date: Fri, 15 Mar 2002
+    <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101620970016263">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101620970016263</link>
+    [FIXME: not yet started summarising]
+   </li>
+   <li>
+    analysis paralysis :-)
+    Date: Mon, 25 Feb 2002
+    <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101465344708301">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101465344708301</link>
+    [FIXME: not yet started summarising]
+   </li>
+   <li>
+    documentation architecture?
+    Date: Thu, 25 Apr 2002
+    <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101973705501466">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101973705501466</link>
+    [FIXME: not yet started summarising]
+   </li>
+   <li>
+    Topic Maps for Forrest ?
+    Date: Mon, 18 Mar 2002
+    <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101647290524645">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101647290524645</link>
+    [FIXME: not yet started summarising]
+   </li>
+  </ul>
+ </section>
+
+ <section>
+ <title>Draft dream list</title>
+
+ <ul>
+  <li>
+   Forrest provides a robust technological infrastructure for open software development for the Apache Software Foundation based on ASF software, ASF practices and experience, and modern software design principles.
+  </li>
+ <li>
+  a publishing system for documentation
+ </li>
+ <li>
+  analysis of logs and publishing of results
+ </li>
+
+ <li>
+Ok, first of all: "it hurts my spirit" (I should TM this) to see the
+apache web sites with such a *poor* information infrastructure. Just
+look at sourceforge: it's not the best site of the world, but gives you
+lots of tools and information that we currently don't have (or have
+hidden someplace).
+ </li>
+
+ <li>
+I want Forrest to be the development infrastructure of your dreams,
+something that you'll be proud of showing your boss and say "if only we
+had this in place, we would save big bucks" so...
+ </li>
+
+ <li>
+  Dream #1: Forrest should make Sourceforge look obsolete.
+ </li>
+
+ <li>
+So, in order for this to happen, it must be dynamic.
+Assumption #1: Forrest is a dynamic site.
+The staticity of apache web sites was mostly due to the quest for heavy
+mirroring, Forrest should allow mirroring, so
+ </li>
+
+ <li>
+  Dream #2: Forrest should reduce xml.apache.org bandwidth use dramatically
+ </li>
+
+ <li>
+  Dream #3: Forrest should automate mirroring in a simple and easy way.
+
+My idea is to use the 'command line' features of Cocoon to generate
+static snapshots of sites and produce mirrors directly using a sort of
+rsync or other mean. Anyway, the goal is to make sure mirroring is as
+easy as possible. No, easier than that.
+ </li>
+
+ <li>
+  coherence: all the site should look coherent, same graphics, same
+look-and-feel, same information in the same locations, coherent and nice URI
+space (build to last! so that broken links are reduced!)
+ </li>
+
+ <li>
+  structure: the site should look professional, the structure should be
+flexible enough to fit every need but solid enough to guide users
+browsing and developers adding resources
+ </li>
+
+ <li>
+  scalability
+ </li>
+
+ <li>
+  functionality: everything you ever wanted to have in your project web site
+ </li>
+
+ <li>
+ logs and community rating: I want to have numbers to judge the value
+of a community/effort
+ </li>
+
+ <li>
+Downloads, number of committers, numbers of people subscribed on the users/dev
+list, numbers of mail messages / week on these lists, CVS activity...
+These are the kind of parameters I use to "judge" an Apache project that I
+have not been looking into before.
+ </li>
+
+ <li>
+  Graphs of various statistics.
+ </li>
+
+ <li>
+Having good site metrics will be a valuable aid to those involved in
+maintenance and future re-design phases.
+See some discussion in
+<link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=102238816218885">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=102238816218885</link>
+ </li>
+
+ <li>
+ Built-in search engine: users much have a simple way to find things.
+ Lucene.
+ </li>
+
+ <li>
+ User-writable pages: people should have a way to add things to the pages.
+ See the thread for more detail on this.
+FIXME: get MARC ref
+ </li>
+
+ <li>
+ short bios for the project committers, with pictures: gives a better
+sense of community. Having a weblog there would be great.
+ </li>
+
+ <li>
+ news, announcements, events and project calendaring: the news and
+the announcements will generate a RSS feed, events will be aggregated
+into a project-wide calendar, or an effort-specific calendar, the events
+will also be overwritten on the logs, to indicate how logs were
+influenced by the events (say, a release or a new committer added)
+ </li>
+
+ <li>
+ book-like PDF versions of documentation: easy to print out docs.
+ </li>
+
+ <li>
+  integration with GUMP: dependencies, runs, committer that broke the run
+ </li>
+
+ <li>
+ javadocs seemlessly integrated with the documentation and with the
+search engine.
+ <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101620970016263">http://marc.theaimsgroup.com/?l=forrest-dev&amp;m=101620970016263</link>
+ </li>
+ 
+ <li>
+ mail archive seemlessly integrated with the search engine (one should
+look for something and get results from either docs, javadocs or emails
+messages)
+ </li>
+
+ <li>
+  coherent-looking CVS view
+ </li>
+
+ <li>
+  document translation using Google translation services
+ </li>
+
+ <li>
+ Integrated project management, task management, bug tracking, feature requests, process management. 
+The idea is to integrate Scarab for bug tracking/patches and
+managing/feature requests.
+(As far as team management, this is a serious political issue and I do not
+want to tackle that one yet, not even on the dreamlist.)
+ </li>
+
+ <li>
+  overview doco for all projects ... CVS Usage precis, overview of opensource
+  and links to relevant doco
+ </li>
+
+</ul>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/dreams.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: forrest/site/docs_0_80/faq.html
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.html?rev=376128&r1=376127&r2=376128&view=diff
==============================================================================
--- forrest/site/docs_0_80/faq.html (original)
+++ forrest/site/docs_0_80/faq.html Wed Feb  8 16:26:20 2006
@@ -517,6 +517,9 @@
 <li>
 <a href="#patch">5.6.  How to contribute a patch? </a>
 </li>
+<li>
+<a href="#jobs">5.7.  How can job positions be advertised? </a>
+</li>
 </ul>
 </li>
 </ul>
@@ -1551,6 +1554,30 @@
           are notes about <a href="../contrib.html#patch">making patches</a>. </p>
 <p>More info about contributing can be found at the <a href="../contrib.html">Contributing
             to Forrest</a> page. It is always a good idea to check the Forrest <a href="../issues.html">issue tracker</a> before diving in. </p>
+</div>
+<a name="N10514"></a><a name="jobs"></a>
+<h4 class="faq">5.7.  How can job positions be advertised? </h4>
+<div align="right">
+<a href="#jobs-menu">^</a>
+</div>
+<div style="margin-left: 15px">
+<p>
+          Employers can send notices about employment opportunities.
+          There is a special jobs&lt;AT&gt;apache.org mailing list.
+          You can also send these notices to the project mailing lists,
+          e.g. dev list at Forrest or Cocoon (add [jobs] to the subject line).
+          You can also approach particular developers off-list. However only
+          genuine jobs, not pleas for free support (see
+          <a href="../mail-lists.html">mailing lists</a>).
+        </p>
+<p>
+          Some enlightened employers enable their employees to contribute
+          material which was created during work time using work-related
+          resources. Please note the need to file a Corporate Contributor
+          License Agreement
+          (<a href="http://www.apache.org/licenses/">CCLA</a>)
+          with The Apache Software Foundation.
+        </p>
 </div>
 </div>
 </div>

Modified: forrest/site/docs_0_80/faq.pdf
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.pdf?rev=376128&r1=376127&r2=376128&view=diff
==============================================================================
Binary files - no diff available.

Added: forrest/site/docs_0_80/faq.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/faq.source.xml (added)
+++ forrest/site/docs_0_80/faq.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,915 @@
+<?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.80//your-project">Using Forrest</link> guide. </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 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>
+      </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 closed and 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.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>
+      </answer>
+    </faq>
+    <faq id="single-document">
+      <question> What is the best way to generate "standalone documents" using Forrest? </question>
+      <answer>
+        <p>
+          There is a trick that can cut down your turnaround time
+          with building. In forrest.properties ...
+        </p>
+
+        <source xml:space="preserve">
+# The URL to start crawling from
+#project.start-uri=linkmap.html
+        </source>
+
+        <p>
+          Uncomment that and set it to the specific page that
+          you want. Forrest will build that page, then of course
+          it will keep crawling links from there. It might be
+          confined to a sub-directory, but depending on links
+          could end up generating the whole site.
+        </p>
+
+        <p>
+          The main thing is that your page of interest is built first.
+          You can terminate forrest with 'kill' or Ctrl-C after it
+          has built your pages of interest.
+        </p>
+
+        <p>
+          Cocoon can be instructed via the
+          <link href="#cli-xconf">Cocoon cli.xconf</link> file to not
+          follow links (see its "follow-links" parameter). So this will
+          build only the document that was specified. Be careful, if you
+          also usually build PDF pages, then they will not be built.
+        </p>
+
+        <p>
+          Cocoon can also be instructed to not process certain URIs
+          if you need to temporarily exclude then.
+        </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.apache.org/jira/secure/ViewIssue.jspa?key=FOR-10">appears
+            to be a bug in cygwin</link>. Please use the .bat script instead. </p>
+      </answer>
+    </faq>
+    <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>main/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>
+    <faq id="debug">
+      <question> How can I start forrest in debug mode? </question>
+      <answer>
+        <p> The <code>forrest.jvmargs</code> property in the <code>forrest.properties</code> file 
+          can be used to start forrest in debug mode on a specific port.
+          <code>forrest.jvmargs=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n</code>
+        </p>
+      </answer>
+    </faq>
+  </part>
+  <part id="content_faqs">
+    <title>Content Creation</title>
+    <faq id="edit-content">
+      <question>What tools can be used to edit the content?</question>
+      <answer>
+        <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>
+      </answer>
+    </faq>
+    <faq id="site-xml">
+      <question>
+        How to use the <code>site.xml</code> configuration file for menus and linking.
+      </question>
+      <answer>
+        <p>
+          The <code>site.xml</code> configuration file is used for two different purposes:
+          defining the 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"><![CDATA[<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"><![CDATA[<a href="site:faq/tech"> link to the top of the Tech FAQs
+<a href="site: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"><![CDATA[<a href="site:docbook"> link to the DocBook FAQ in the Tech FAQs]]></source>
+      </answer>
+    </faq>
+    <faq id="examples">
+      <question>
+        Where are examples of documents and site.xml and tabs.xml files?
+      </question>
+      <answer>
+        <p>
+          There are examples in the 'forrest seed site' and also the Forrest website documents
+          are included with the distribution (<code>cd forrest/site-author;
+            forrest run</code>).
+        </p>
+      </answer>
+    </faq>
+    <faq id="crawler">
+      <question>
+        Help, one of my documents is not being rendered.
+      </question>
+      <answer>
+        <p>
+          Did you make a link to it? Forrest does not find documents by scanning
+          the filesystem to find the source documents. Rather it starts at one
+          document and crawls the links to find other documents to process.
+        </p>
+        <p>
+          There are essentially two ways to create links. Via a site.xml file to define the
+          navigation and menu structure, or via direct relative linking. See the
+          to previous FAQs.
+        </p>
+        <p>
+          Normally the source material will be local. The Forrest crawler does not follow
+          and process off-site links. The new locationmap (0.8+) enables content
+          to be drawn from remote sources.
+          
+        </p>
+      </answer>
+    </faq>
+    <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.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>
+      </answer>
+    </faq>
+    <faq id="pageBreaks">
+      <question>How do I insert page breaks into documents?</question>
+      <answer>
+        <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>
+      </answer>
+    </faq>
+    <faq id="clickable-email-address">
+      <question>How can I generate html-pages to show a 'clickable' email-address (of the
+        author-element)?</question>
+      <answer>
+        <p>You would override <code>
+            $FORREST_HOME/main/webapp/skins/common/xslt/html/document2html.xsl</code> and edit the
+          "headers/authors" template. </p>
+      </answer>
+    </faq>
+    <faq id="link_raw">
+      <question>How do I link to raw files such as config.txt and brochure.pdf? </question>
+      <answer>
+        <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>
+      </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
+          <code>http://java.sun.com/products/java-media/jai</code>). 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="tab-index">
+      <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="tab-site">
+      <question>I need help with the interaction between tabs.xml and site.xml </question>
+      <answer>
+        <p>
+          See the <link href="site:v0.80//linking/tab-site">tips</link>.
+        </p>
+      </answer>
+    </faq>
+    <faq id="defaultFileName">
+      <question> 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> ? </question>
+      <answer>
+        <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
+            <![CDATA[<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"><![CDATA[
+  <map:pipeline>
+    <map:match type="regexp" pattern="^.+/$">
+       <map:redirect-to uri="overview.html"/>
+    </map:match>
+  </map:pipeline>
+          ]]></source></li>
+        </ol>
+      </answer>
+    </faq>
+    <faq id="defaultStartPage">
+      <question> How can I use a start-up-page other than index.html? </question>
+      <answer>
+        <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"><![CDATA[
+  <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>
+      </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[&ouml;]]></code> use <code><![CDATA[&#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>
+      </answer>
+    </faq>
+    <faq id="encoding">
+      <question>Does Forrest handle accents for non-English languages?</question>
+      <answer>
+        <p>Yes, Forrest can process text in any language, so you can include:</p>
+        <ul>
+          <li>accents: á é í ó ú</li>
+          <li>diereses: ä ë ï ö ü</li>
+          <li>tildes: ã ñ &#297; õ &#361;</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"><![CDATA[<?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"><![CDATA[<?xml version="1.0" encoding="ISO-8859-1"?>]]></source>
+        <p>Another option is to use "character entities" such as <code><![CDATA[&ouml;]]></code>
+          (ö) or the numeric form <code><![CDATA[&#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>
+      </answer>
+    </faq>
+    <faq id="xml-entities">
+      <question>How to use XML entities, for example string
+        replacement?</question>
+      <answer>
+        <p>
+          A set of symbols is available. See the demonstration
+          in a fresh 'forrest seed' site (at samples/xml-entities.html).
+          For example, use "<code>&amp;myp-t;</code>" to represent the
+          project name together with trademark symbol
+          "My Project Name&#8482;".
+          Avoid lengthy typing and potential spelling errors.
+        </p>
+      </answer>
+    </faq>
+    <faq id="cleanSite">
+      <question> How to make Forrest clean up the project build directories? </question>
+      <answer>
+        <p>
+          By default Forrest does not clean its build directories in the project
+          workspaces. This enables Cocoon to use its disk cache to speed up
+          successive runs of forrest.
+        </p>
+        <p>
+        Doing 'forrest clean-site' will remove the contents of the project's
+        generated documents directory. Doing 'forrest clean-work' will remove the
+        project's work directories (usually build/tmp and build/webapp which
+        include the Cocoon cache and the Cocoon logs).
+        Doing 'forrest clean' will remove both sections.
+        </p>
+      </answer>
+    </faq>
+    <faq id="i18n">
+      <question>How can I internationalise (i18n) my content?</question>
+      <answer>
+        <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/i18nTransformer.html">Cocoon i18n 
+        Transformer</link>. You can see an example of how it works in the above linked issue.</p>
+      </answer>
+    </faq>
+    <faq id="rawTML">
+      <question>How can I include HTML content that is not to be skinned by Forrest?</question>
+      <answer>
+        <p>To serve, for example a legacy HTML site, add something like the following 
+        to your project's sitemap and place the source content at the
+        <code>src/documentation/content/xdocs/old_site/</code> directory.</p>
+        <source xml:space="preserve">
+&lt;map:match pattern="old_site/**.html"&gt;
+ &lt;map:select type="exists"&gt;
+  &lt;map:when test="{project:content}{0}"&gt;
+    &lt;map:read src="{project:content}/{0}" mime-type="text/html"/&gt;
+    &lt;!--
+      Use this instead if you want JTidy to clean up your HTML
+      &lt;map:generate type="html" src="{project:content}/{0}" /&gt;
+      &lt;map:serialize type="html"/&gt;
+    --&gt;
+  &lt;/map:when&gt;
+ &lt;/map:select&gt;
+&lt;/map:match&gt;
+        </source>
+        <p>There is a more detailed discussion of this topic in the samples
+        of a freshly seeded site. To see this documentation do the following:</p>
+        <ol>
+          <li>mkdir seed</li>
+          <li>cd seed</li>
+          <li>forrest seed-sample</li>
+          <li>forrest</li>
+          <li><link href="http://localhost:8888/samples/linking.html#no-decoration">Read the doc</link></li>
+        </ol>
+      </answer>
+    </faq>
+
+    <faq id="javascript">
+      <question>How to include additional Javascript and CSS files?</question>
+      <answer>
+        <p>
+          Place various resources (e.g. javascript, css) into the
+          "project skins" directory. The default forrest.properties
+          has this at src/documentation/skins/$skin-name/
+          Javascript files would go in a "scripts" subdirectory.
+          CSS files would go in a "css" subdirectory.
+        </p>
+        <p>
+          Then refer to those from your source documents with
+          URIs like /skin/blah.js and /skin/foo.css
+        </p>
+        <p>
+          See how this is handled in the core sitemap
+          called forrest/main/webapp/resources.xmap
+          Search for "javascript" then follow to the 
+          &lt;map:resource name="skin-read"&gt; section.
+        </p>
+      </answer>
+    </faq>
+  </part>
+  <part id="technical">
+    <title>Technical</title>
+    <faq id="proxy_config">
+      <question>I'm behind a proxy and it's preventing Plugins from being downloaded, what should I
+        do?</question>
+      <answer>
+        <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.</p>
+        <p>You can also cross an authenticated proxy by setting the <code>proxy.user</code> and <code>proxy.password</code> accordingly.</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>&lt;version&gt;$Revision: 1.30
+          $&lt;/version&gt;</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>
+      </answer>
+    </faq>
+    <faq id="cli-xconf">
+      <question> How to control the processing of URIs by Cocoon, e.g. exclude certain URIs, include
+        other additional ones. </question>
+      <answer>
+        <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"><![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.80//sitemap-ref">sitemap</link>. For example, <strong>foo/*</strong> would match
+            <code>foo/bar</code>, but not <code>foo/bar/baz</code> &#8212; use
+          <strong>foo/**</strong> to match that. </note>
+      </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 <link href="#cli-xconf">
+            <code>cli.xconf</code>
+          </link> Cocoon config file, and defining patterns for URLs to exclude. </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. 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>
+      </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>
+        <p>
+          Each time that Cocoon processes a link, it will report the status messages ...
+        </p>
+        <source xml:space="preserve"><![CDATA[...
+* [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 (pagesComplete/pagesRemaining). 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 (newLinksInPage/linksInPage).</li>
+          <li>Column 4 is the time taken.</li>
+          <li>Column 5 is the page size.</li>
+        </ul>
+      </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="project-logo-svg">
+      <question> 
+        The project logo that is generated from SVG is truncating my project name.
+      </question>
+      <answer>
+        <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>&lt;project-name&gt;</code> and
+          <code>&lt;group-name&gt;</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 &lt;svg&gt; element. For further details see
+          <link href="http://www.w3.org/Graphics/SVG/">SVG</link> resources.
+        </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.80//catalog">Using Catalog Entity
+            Resolver for local DTDs</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.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>
+      </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://svn.apache.org/repos/asf/cocoon/trunk/lib/optional/">jdtcore-*.jar</link> from Cocoons SVN tree, 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"><![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>
+    <faq id="run_port">
+      <question>How do I make <code>forrest run</code> listen on a different port?</question>
+      <answer>
+        <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>
+      </answer>
+    </faq>
+    <faq id="debugging">
+      <question>Can I run Forrest with Java debugging turned on?</question>
+      <answer>
+        <p>If you use an IDE like Eclipse and want to debug java code in Forrest
+        you need to start Forrest with debugging mode turned on. To do this you need
+        to add <code>-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,susp end=n</code>
+        to the <code>forrest.jvmargs</code> property in the <code>forrest.properties</code>
+        file. Don't forget to ensure the property is uncommented in that file.</p>
+      </answer>
+    </faq>
+    <faq id="checksums">
+      <question>How do I enable Cocoon's document checksum feature?</question>
+      <answer>
+        <p>
+        Why might you want to do this?  There is really no effect
+        on Cocoon processing, but a little time can be
+        saved on filesystem writes, which will accumulate
+        to a big savings for a site with thousands of files.
+        </p>
+        <p>
+          Another reason could be if you are not using the forrestbot to
+          deploy the generated site. Some tools depend on the "date-last-modified"
+          timestamp of the generated files.
+        </p>
+        <p>
+        There was some discussion about this on the Forrest developer mailing
+        list:
+        <link href="http://marc.theaimsgroup.com/?l=forrest-dev&amp;s=cocoon+checksum">Cocoon Checksum</link> 
+        Specifically note that this feature only stops Cocoon from writing to 
+        disk if the new file is the same as the existing file.  Cocoon still spends
+        the same amount of time generating the content as it would if checksums
+        were not enabled.
+        </p>
+        <p>
+        Locate the <code>checksums-uri</code> tag within cli.xconf and replace
+        the contents with an absolute path and filename for the checksums file.
+        Projects can supply their own (see FAQ:
+        <link href="#cli-xconf">Cocoon cli.xconf</link>) or use the default
+        installation-wide cli.xconf file.
+        </p>
+      </answer>
+    </faq>
+  </part>
+  <part id="old_faqs">
+    <title>Older version: 0.6</title>
+    <faq id="old_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. 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>
+      </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.80//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 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"><![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 need to define the xhtml serializer used in &lt;map:serialize type="xhtml"/&gt;
+        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>
+      </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>main/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/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&#8212;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> before diving in. </p>
+      </answer>
+    </faq>
+    <faq id="jobs">
+      <question> How can job positions be advertised? </question>
+      <answer>
+        <p>
+          Employers can send notices about employment opportunities.
+          There is a special jobs&lt;AT&gt;apache.org mailing list.
+          You can also send these notices to the project mailing lists,
+          e.g. dev list at Forrest or Cocoon (add [jobs] to the subject line).
+          You can also approach particular developers off-list. However only
+          genuine jobs, not pleas for free support (see
+          <link href="site:mail-lists">mailing lists</link>).
+        </p>
+        <p>
+          Some enlightened employers enable their employees to contribute
+          material which was created during work time using work-related
+          resources. Please note the need to file a Corporate Contributor
+          License Agreement
+          (<link href="http://www.apache.org/licenses/">CCLA</link>)
+          with The Apache Software Foundation.
+        </p>
+      </answer>
+    </faq>
+  </part>
+</faqs>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/faq.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: forrest/site/docs_0_80/faq.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/faq.xml?rev=376128&r1=376127&r2=376128&view=diff
==============================================================================
--- forrest/site/docs_0_80/faq.xml (original)
+++ forrest/site/docs_0_80/faq.xml Wed Feb  8 16:26:20 2006
@@ -672,4 +672,22 @@
           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 id="jobs"><title>5.7.  How can job positions be advertised? </title>
+        <p>
+          Employers can send notices about employment opportunities.
+          There is a special jobs&lt;AT&gt;apache.org mailing list.
+          You can also send these notices to the project mailing lists,
+          e.g. dev list at Forrest or Cocoon (add [jobs] to the subject line).
+          You can also approach particular developers off-list. However only
+          genuine jobs, not pleas for free support (see
+          <link href="site:mail-lists">mailing lists</link>).
+        </p>
+        <p>
+          Some enlightened employers enable their employees to contribute
+          material which was created during work time using work-related
+          resources. Please note the need to file a Corporate Contributor
+          License Agreement
+          (<link href="http://www.apache.org/licenses/">CCLA</link>)
+          with The Apache Software Foundation.
+        </p>
       </section></section></section></body></document>

Added: forrest/site/docs_0_80/forrest-contract.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/forrest-contract.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/forrest-contract.source.xml (added)
+++ forrest/site/docs_0_80/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>{docroot}/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_80/forrest-contract.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native

Added: forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.source.xml
URL: http://svn.apache.org/viewcvs/forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.source.xml?rev=376128&view=auto
==============================================================================
--- forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.source.xml (added)
+++ forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.source.xml Wed Feb  8 16:26:20 2006
@@ -0,0 +1,157 @@
+<?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>CVS through SSH</title>
+        <version>1.0</version>
+        <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.</abstract>
+        <last-modified-content-date date="2002-05-27"/>
+    </header><body><section id="Intended audience"><title>Intended audience</title>
+        <p>This How-to is aimed at developers who have been granted committer access to CVS repositories for particular projects.</p>
+    </section><section id="Purpose"><title>Purpose</title>
+        <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>
+    </section><section id="Prerequisites"><title>Prerequisites</title>
+        <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 <link href="http://www.redhat.com/software/tools/cygwin/">here</link>. <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>
+        <note>If you are behind a firewall check that you can communicate through the 22 port. For anonymous access you will need 2401 one.</note>
+    </section><section id="Steps"><title>Steps</title>
+        <p>How to proceed.</p>
+        <section>
+            <title>Terms</title>
+            <dl>
+        <dt>SSH</dt>
+        <dd>Secure Shell. See <link href="http://www.openssh.org">OpenSSH</link></dd>
+        <dt>CVS</dt>
+        <dd>Concurrent Version System See <link href="http://www.cvshome.org">CVS Home Page</link></dd>
+         </dl>                    
+        </section>
+        <note><strong>$</strong> represents local, <strong>%</strong> remote machine.</note>                
+        <section>
+            <title>Setting up domain users</title>
+            <note>This step is necessary only for Windows users. Linux users can happily skip this section and pass to <link href="#ssh_access">Setting up SSH access</link> section</note>
+            <p>If you are a domain user then you should be added to Cygwin users list (See <code>[cygwin-dir]/etc/passwd</code>). 
+            </p>
+            <ul>
+              <li>Start Cygwin, then enter following commands:</li>
+            </ul>
+            <source xml:space="preserve">
+$ whoami
+administrator
+$ mkgroup -d &gt; /etc/group
+$ mkpasswd -d | grep 'userxxx' &gt;&gt; /etc/passwd
+$ exit
+    </source>
+       <note>Replace 'userxxx' by your account name</note>    
+    <ul>
+      <li>Start Cygwin/shell again and check that everything's Ok:</li>
+    </ul>
+    <source xml:space="preserve">
+$ whoami
+userxxx
+            </source>
+        </section>
+        <section id="ssh_access">
+            <title>Setting up SSH access</title>
+            <p>Start Cygwin/shell, then enter:</p>
+            <source xml:space="preserve">
+$ 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!
+    </source>
+    <p>
+      Now you have configured SSH on your machine. Next you have to setup access to the CVS machine.
+    </p>
+    <warning>Having an empty passphrase isn't recommended for security reasons. See <code>ssh-agent</code> documentation on how to configure automatic passphrase retaining.</warning>
+        </section>
+        <section>
+            <title>Setting up passphrase access</title>
+            <p>Perform the following:</p>
+            <source xml:space="preserve">
+$ 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 &gt;&gt; ~/.ssh/authorized_keys2
+% rm ~/id_dsa.pub
+% chmod 600 ~/.ssh/*
+% exit            
+            </source>
+            <note>Note, that the account name on CVS machine can differ from your local account name.</note>
+            <p>
+            Check that your configuration is correct:
+            </p>
+            <source xml:space="preserve">
+$ ssh userxxx@cvs.apache.org
+            </source>
+            <note>If this command doesn't work then it can mean that you have an old version of SSH. In this case try <code>ssh -l userxxx cvs.apache.org</code>. Run <code>ssh --help</code> to get all available options.</note>
+            <p>
+            If now you are logged in to the to the CVS machine without entering the password then everything's Ok.
+            </p>           
+        </section>
+        <section>
+            <title>Getting the project from CVS</title>
+            <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>
+            <source xml:space="preserve">
+$ export CVS_RSH=/bin/ssh
+$ cvs -d :ext:userxxx@cvs.apache.org:/home/cvs co xml-cocoon2            
+            </source>
+        </section>
+        <section>
+            <title>How to setup WinCVS</title>
+            <ul>
+                <li>Add ssh.exe directory to your system PATH environment variable. Say: <br/>
+                <code>C:\&gt;set PATH=%PATH%;C:\cygwin\bin</code></li>
+                <li>Add <code>CVS_RSH=ssh</code> 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 <code>userxxx@cvs.apache.org:/home/cvs</code></li>
+                <li>Set the Authentication to SSH Server</li>                
+                <li>Click Ok</li>
+            </ul>
+        </section>
+        <section>
+            <title>References</title>
+            <p>
+                You can find more on CVS, SSH and WinCVS here:
+            </p>
+            <ul>
+                <li><link href="http://www.cvshome.org">CVS Home Page</link></li>            
+                <li><link href="http://www.openssh.org">OpenSSH</link></li>            
+                <li><link href="http://www.redhat.com/software/tools/cygwin/">Cygwin Home Page</link></li>            
+                <li><link href="http://odin.himinbi.org/wincvs-over-ssh/">WinCVS over SSH</link></li>
+            </ul>
+        </section>
+    </section></body></document>
\ No newline at end of file

Propchange: forrest/site/docs_0_80/howto/cvs-ssh/howto-cvs-ssh.source.xml
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message