etc/RELEASE-NOTES-0.2.txt - forrest - Git at Google

                                Apache Forrest 0.2
                                  Release Notes
                           ============================

 $Id: RELEASE-NOTES-0.2.txt,v 1.7 2002/11/16 13:19:31 jefft Exp $

 1) Introduction
 ---------------

 This document describes the 0.2 release of Apache Forrest, how to get started,
 known bugs and any other issues.  Please send all feedback to
 forrest-dev@xml.apache.org

 2)  Status
 ----------

 This 0.2 release is believed to be stable, and is in use by many projects
 (including xml.apache.org).  However, forrest-dev explicitly DOES NOT intend to
 maintain the degree of accountability and backwards-compatibility intended for
 future 0.x releases.  This 0.2 release is made primarily to meet user demand,
 to solicit feedback, and to give the Forrest community a trial run in the
 process of Forrest releases.


 3) What is Forrest?
 -------------------

 Forrest is an XML standards-oriented project documentation framework based on
 Apache Cocoon, providing XSLT stylesheets and schemas, images and other
 resources. Forrest uses these to render the XML source content into a website
 via command-line, robot, or a dynamic web application.  For more details,
 please see the website at http://xml.apache.org/forrest/

 4) Requirements
 ---------------

 - The Forrest binary distribution requires a Java Runtime Environment (1.2 or
   higher) installed.  This can be obtained from
   http://java.sun.com/j2se/downloads.html

 - The Forrest source distribution requires a Java Development Kit (1.2 or
   higher) to build, obtainable from the same URL.

 Ant is not required: Forrest uses its own stripped-down, souped-up Ant in
 tools/ant/


 5) Installing Forrest
 ---------------------

 Depending on which distribution you downloaded, one of these sections will
 apply to you.

 o 5.1) Source distribution
   ------------------------

   The source distribution contains static Forrest resources (skins, XSLTs,
   images, schemas), source code and Forrest's own website.

   - To build the Forrest binary distribution, type:

     build.bat    (Windows)
     ./build.sh   (Unix)

     (if Ant 1.5+ is installed, typing 'ant' works just as well)

     A binary distribution will be built in build/dist/shbat Add the path to
     build/dist/shbat/bin to your PATH environment variable, and you have
     Forrest installed.  Windows users (esp. 95/98) may need to set FORREST_HOME
     to point to the build/dist/shbat directory.

 o 5.2) Binary distribution
   ------------------------

   The binary distribution contains a static reusable Forrest ready for use.

   - Copy somewhere permanent, like /usr/local/forrest or c:\forrest.
     Support for installation on Windows systems into directories containing
     spaces is very new, please report back on your success or failure.

   - Windows users should set the FORREST_HOME environment variable to point to
     where Forrest is installed.
   - Add $FORREST_HOME/bin (Unix) or %FORREST_HOME%\bin (Windows) to the system
     PATH environment variable.


 6) Getting Started
 ------------------


 Having installed Forrest, here is a little test sequence to validate that
 everything works, and to get you started.  For more information, see
 http://xml.apache.org/forrest/your-project.html

  - Type 'forrest -projecthelp'.  This should list the available Forrest
    commands.
    NOTE: use the 'forrest.bat' version when running under Cygwin!

  - Create an empty directory somewhere, and change cd to it.

    [ e.g. mkdir /tmp/mysite ; cd /tmp/mysite ]

  - Type 'forrest seed'.  This will create a template site in the current
    directory, ready for you to edit or render.

  - (optional) Edit the XML content in src/documentation/content/xdocs
    Have a look around, familiarize yourself with the structure.

  - In your new project root [ e.g. /tmp/mysite ],  type 'forrest validate'.
    This will check that all XML files are valid.  Actually Forrest does this
    automatically for the next step, but we're proud of our validation :)

  - In the project root, type 'forrest' or 'forrest site'.  This will generate
    HTML for your project in build/site

  - (optional) Type 'forrest run'.  This starts up an internal webserver
    displaying the project contents rendered at runtime.  Point your browser at
    http://localhost:8888/ to see your site.  Edits to files in build/webapps
    are instantly rendered.  See the site docs for more info on how to exploit
    this capability.


 7) Known bugs
 -------------

  7.1)
    "I've seen one bug... Suppose you have "mypage.html" and "mypage-two.html"
    in the book.xml. Then, two links are renedered in yellow when first page is
    accessed. Anyone else seen this?"

      Vadim Gritsenko, <3DCFDAEA.1050209@verizon.net>

  7.2)
    When running a Forrest site as a webapp, a user reports:

    "When I call a page for second time, it should be cached.  But as we can see
    in the logs attached, it is not, although the 3 aggregated xml (book, tabs
    and body) are cached.

    Another problem is the evaluation of the xslt just before the cache
    validation. In the documents is too much time consuming, as you can see in
    the logs."

      <20021107161831.80475.qmail@web21309.mail.yahoo.com>

    In a later post <20021108171056.14103.qmail@web21301.mail.yahoo.com>, a fix
    (comment out JispFilesystemStore in cocoon.xconf) is suggested.

  7.3)
    The Forrest website http://xml.apache.org/forrest/ is somewhat
    unrepresentative of what Forrest actually is.  The most up-to-date section
    is http://xml.apache.org/forrest/your-project.html


 8) Known limitations
 --------------------

   8.1)
     Forrest has no way to indicate that certain links should not be traversed.
     Thus, links to external files like Javadocs will cause non-fatal errors
     when building docs:

     -> [broken link] api/index.html <-

     http://marc.theaimsgroup.com/?l=forrest-dev&m=103739834606109&w=2 might help,
     but is untested.

   8.2)
     When Forrest is run through http://localhost:8888/, docs in build/webapp/
     are rendered, not src/documentation/*.  Thus, symlinks are required for
     live editing.  Editing docs directly in build/webapp/ is NOT recommended,
     they will be deleted on the next 'forrest' invocation.


 --
 $Revision: 1.7 $ $Date: 2002/11/16 13:19:31 $
	Apache Forrest 0.2
	Release Notes
	============================

	$Id: RELEASE-NOTES-0.2.txt,v 1.7 2002/11/16 13:19:31 jefft Exp $

	1) Introduction
	---------------

	This document describes the 0.2 release of Apache Forrest, how to get started,
	known bugs and any other issues. Please send all feedback to
	forrest-dev@xml.apache.org

	2) Status
	----------

	This 0.2 release is believed to be stable, and is in use by many projects
	(including xml.apache.org). However, forrest-dev explicitly DOES NOT intend to
	maintain the degree of accountability and backwards-compatibility intended for
	future 0.x releases. This 0.2 release is made primarily to meet user demand,
	to solicit feedback, and to give the Forrest community a trial run in the
	process of Forrest releases.


	3) What is Forrest?
	-------------------

	Forrest is an XML standards-oriented project documentation framework based on
	Apache Cocoon, providing XSLT stylesheets and schemas, images and other
	resources. Forrest uses these to render the XML source content into a website
	via command-line, robot, or a dynamic web application. For more details,
	please see the website at http://xml.apache.org/forrest/

	4) Requirements
	---------------

	- The Forrest binary distribution requires a Java Runtime Environment (1.2 or
	higher) installed. This can be obtained from
	http://java.sun.com/j2se/downloads.html

	- The Forrest source distribution requires a Java Development Kit (1.2 or
	higher) to build, obtainable from the same URL.

	Ant is not required: Forrest uses its own stripped-down, souped-up Ant in
	tools/ant/


	5) Installing Forrest
	---------------------

	Depending on which distribution you downloaded, one of these sections will
	apply to you.

	o 5.1) Source distribution
	------------------------

	The source distribution contains static Forrest resources (skins, XSLTs,
	images, schemas), source code and Forrest's own website.

	- To build the Forrest binary distribution, type:

	build.bat (Windows)
	./build.sh (Unix)

	(if Ant 1.5+ is installed, typing 'ant' works just as well)

	A binary distribution will be built in build/dist/shbat Add the path to
	build/dist/shbat/bin to your PATH environment variable, and you have
	Forrest installed. Windows users (esp. 95/98) may need to set FORREST_HOME
	to point to the build/dist/shbat directory.

	o 5.2) Binary distribution
	------------------------

	The binary distribution contains a static reusable Forrest ready for use.

	- Copy somewhere permanent, like /usr/local/forrest or c:\forrest.
	Support for installation on Windows systems into directories containing
	spaces is very new, please report back on your success or failure.

	- Windows users should set the FORREST_HOME environment variable to point to
	where Forrest is installed.
	- Add $FORREST_HOME/bin (Unix) or %FORREST_HOME%\bin (Windows) to the system
	PATH environment variable.


	6) Getting Started
	------------------


	Having installed Forrest, here is a little test sequence to validate that
	everything works, and to get you started. For more information, see
	http://xml.apache.org/forrest/your-project.html

	- Type 'forrest -projecthelp'. This should list the available Forrest
	commands.
	NOTE: use the 'forrest.bat' version when running under Cygwin!

	- Create an empty directory somewhere, and change cd to it.

	[ e.g. mkdir /tmp/mysite ; cd /tmp/mysite ]

	- Type 'forrest seed'. This will create a template site in the current
	directory, ready for you to edit or render.

	- (optional) Edit the XML content in src/documentation/content/xdocs
	Have a look around, familiarize yourself with the structure.

	- In your new project root [ e.g. /tmp/mysite ], type 'forrest validate'.
	This will check that all XML files are valid. Actually Forrest does this
	automatically for the next step, but we're proud of our validation :)

	- In the project root, type 'forrest' or 'forrest site'. This will generate
	HTML for your project in build/site

	- (optional) Type 'forrest run'. This starts up an internal webserver
	displaying the project contents rendered at runtime. Point your browser at
	http://localhost:8888/ to see your site. Edits to files in build/webapps
	are instantly rendered. See the site docs for more info on how to exploit
	this capability.



	7) Known bugs
	-------------

	7.1)
	"I've seen one bug... Suppose you have "mypage.html" and "mypage-two.html"
	in the book.xml. Then, two links are renedered in yellow when first page is
	accessed. Anyone else seen this?"

	Vadim Gritsenko, <3DCFDAEA.1050209@verizon.net>

	7.2)
	When running a Forrest site as a webapp, a user reports:

	"When I call a page for second time, it should be cached. But as we can see
	in the logs attached, it is not, although the 3 aggregated xml (book, tabs
	and body) are cached.

	Another problem is the evaluation of the xslt just before the cache
	validation. In the documents is too much time consuming, as you can see in
	the logs."

	<20021107161831.80475.qmail@web21309.mail.yahoo.com>

	In a later post <20021108171056.14103.qmail@web21301.mail.yahoo.com>, a fix
	(comment out JispFilesystemStore in cocoon.xconf) is suggested.

	7.3)
	The Forrest website http://xml.apache.org/forrest/ is somewhat
	unrepresentative of what Forrest actually is. The most up-to-date section
	is http://xml.apache.org/forrest/your-project.html


	8) Known limitations
	--------------------

	8.1)
	Forrest has no way to indicate that certain links should not be traversed.
	Thus, links to external files like Javadocs will cause non-fatal errors
	when building docs:

	-> [broken link] api/index.html <-

	http://marc.theaimsgroup.com/?l=forrest-dev&m=103739834606109&w=2 might help,
	but is untested.

	8.2)
	When Forrest is run through http://localhost:8888/, docs in build/webapp/
	are rendered, not src/documentation/*. Thus, symlinks are required for
	live editing. Editing docs directly in build/webapp/ is NOT recommended,
	they will be deleted on the next 'forrest' invocation.


	--
	$Revision: 1.7 $ $Date: 2002/11/16 13:19:31 $