Propchange: forrest/site/docs_0_90/howto/howto-editcss.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_90/howto/howto-forrest-from-maven.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/howto-forrest-from-maven.html?view=auto&rev=529910 ============================================================================== --- forrest/site/docs_0_90/howto/howto-forrest-from-maven.html (added) +++ forrest/site/docs_0_90/howto/howto-forrest-from-maven.html Wed Apr 18 01:10:58 2007 @@ -0,0 +1,477 @@ + + + + + + + +How to run Forrest from within Maven (v0.9-dev) + + + + + + + + + +
+ +
+apache > forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+ +
Font size: +   +   +   +
+

How to run Forrest from within Maven

+
+ This How-To describes how to run Forrest from within Maven. +
+
+ This is documentation for development version v0.9-dev + (More)
+ + +

Intended Audience

+
+

+ Users who want to run Forrest from within Maven. +

+
+ +

Purpose

+
+

+ One may want to generate their project's documentation and/or website + using Forrest in lieu of Maven's site plugin. +

+
+ +

Prerequisites

+
+
    + +
  • Understand how to add goals to maven.xml.
  • + +
+
+ +

Steps

+
+

+ The procedure outlined below describes how to add a goal to your project's + maven.xml that will invoke Forrest's site target. +

+ +

Set the FORREST_HOME environment variable

+

+ Make sure the FORREST_HOME environment variable points to your Forrest + home directory (i.e. the directory that contains + forrest.build.xml) (e.g. C:\opt\apache-forrest-0.7) +

+ +

Initialize an Ant environment property at the top of + maven.xml

+

+ Paste the following line at the top of your maven.xml: +

+
+<property environment="env" />
+      
+ +

Add forrest goal to maven.xml

+

+ Paste the following goal into your project's maven.xml: +

+
+<goal name="forrest" description="runs Forrest">
+  <property name="forrest.home" location="${env.FORREST_HOME}" />
+  <property name="forrest.ant.home" location="${forrest.home}/tools/ant" />
+  <java classname="org.apache.tools.ant.Main" fork="true" failonerror="true" maxmemory="128M">
+    <classpath>
+      <fileset dir="${forrest.ant.home}/lib">
+        <include name="*.jar" />
+      </fileset>
+      <pathelement path="${java.home}/../lib/tools.jar" />
+    </classpath>
+    <sysproperty key="ant.home" value="${forrest.ant.home}" />
+    <sysproperty key="forrest.home" value="${forrest.home}" />
+    <sysproperty key="basedir" value="${basedir}" />
+    <sysproperty key="java.endorsed.dirs" value="${forrest.home}/lib/endorsed" />
+    <arg line="-f ${forrest.home}/main/forrest.build.xml" />
+  </java>
+</goal>      
+      
+

+ It is necessary to fork a separate java process because Maven 1.0 embeds + Ant 1.5.2, but Forrest's forrest.build.xml requires Ant 1.6. The goal + makes use of the copy of Ant 1.6 that is bundled with Forrest, so it's + not even necessary to have Ant 1.6 installed separately. +

+ +

Alternative file

+

+ Under $FORREST_HOME/tools/targets/maven.xml + +

+
+ +

Feedback

+
+

+ Please provide feedback about this document via the + mailing lists. + +

+
+
+ +
 
+
+ + + Propchange: forrest/site/docs_0_90/howto/howto-forrest-from-maven.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_90/howto/howto-forrest-from-maven.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/howto-forrest-from-maven.pdf?view=auto&rev=529910 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_90/howto/howto-forrest-from-maven.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_90/howto/howto-pdf-tab.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/howto-pdf-tab.html?view=auto&rev=529910 ============================================================================== --- forrest/site/docs_0_90/howto/howto-pdf-tab.html (added) +++ forrest/site/docs_0_90/howto/howto-pdf-tab.html Wed Apr 18 01:10:58 2007 @@ -0,0 +1,615 @@ + + + + + + + +How to create a PDF document for each tab (v0.9-dev) + + + + + + + + + +
+ +
+apache > forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+ +
Font size: +   +   +   +
+

How to create a PDF document for each tab

+
+ This How-To describes the generation of a PDF document for each group of + documents that is defined by a tab. +
+
+ This is documentation for development version v0.9-dev + (More)
+ + +

Intended Audience

+
+

+ Users who need to generate one printable document aggregated from a group + of documents. +

+
+ +

Purpose

+
+

+ By default Forrest generates a pdf file for each separate document of your + project. As well you can create a pdf of the whole site. But sometimes it + may be necessary to generate a pdf file out of selected tab, i.e. only for + certain parts of the site. +

+
+ +

Prerequisites

+
+
    + +
  • Understand how to create project-specific sitemaps by following the + Using Forrest document.
  • + +
+
+ +

Steps

+
+

+ The procedure outlined below will define a project + sitemap.xmap and create a new pdf-tab.xmap. +

+ +

Create your project's main sitemap.xmap

+

+ If you do not have already a sitemap then create a new empty one in your + src/documentation directory (or wherever + ${project.sitemap-dir} points to). +

+ +

Create another sitemap: pdf-tab.xmap

+

+ Like before create an empty sitemap and name it pdf-tab.xmap. +

+ +

Edit project sitemap.xmap to mount pdf-tab.xmap

+

+ Your sitemap should look something like this. +

+
+
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+  <map:pipelines>
+    <map:pipeline internal-only="false">
+      <map:match pattern="**.xml">
+        <!-- pdf-tab definitions -->
+        <map:match pattern="pdf-tab.xml">
+          <map:mount uri-prefix="" src="pdf-tab.xmap"
+            check-reload="yes" />
+        </map:match>
+        <!-- end of pdf-tab definitions -->
+      </map:match>
+    </map:pipeline>
+  </map:pipelines>
+</map:sitemap>
+      
+ +

Edit the file pdf-tab.xmap

+

+ The +<map:match pattern="*.xml"> + element should look like the following: +

+
+
+<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+  <map:pipelines>
+    <map:pipeline internal-only="false">
+     <map:match pattern="*.xml">
+	<map:generate src="cocoon://abs-linkmap"/>
+	  <map:transform type="xpath">
+	  	<map:parameter name="include" value="//*[@wholesite='true']"/>
+		<map:parameter name="exclude" value="//*[@wholesite='false']"/>
+	  </map:transform>
+	  <map:transform src="resources/stylesheets/site2book.xsl" />
+	  <map:transform src="resources/stylesheets/aggregates/book2cinclude.xsl">
+	     <map:parameter name="title"
+		value="{conf:project-name}: Still My Foo Site"/>
+	     </map:transform>
+	  <map:transform type="cinclude"/>
+	  <map:transform src="resources/stylesheets/aggregates/doc2doc-uniqueids.xsl"/>
+	  <map:transform src="resources/stylesheets/aggregates/docs2document.xsl"/>
+	  <map:serialize type="xml"/>
+    </map:match>    
+   </map:pipeline>
+  </map:pipelines>
+</map:sitemap>
+      
+ +

Edit your site.xml

+
+
Note
+
+ Do not use directories with "." in it. Replace them by "_" e.g 1.2/ will + not work in the aggregation. e.g. 1_2/ just works fine. +
+
+

+ Add the following entry to your site.xml in the +<about> + element +

+
+... 
+<whole_foosite href="pdf-tab.html" label="sub site" />
+      
+

+ Your site.xml should look like this ... +

+
+... 
+<about label="About">
+  <index label="Index" href="index.html" description="Welcome to MyProj"/>
+  <changes label="Changes" href="changes.html"
+    description="History of Changes" />
+  <todo label="Todo" href="todo.html" description="Todo List" />
+  <whole_foosite href="pdf-tab.html" label="pdf-tab" />
+</about>
+...
+      
+

+ This allows you to link to it via a +<link href="site:whole_foosite"> + reference. +

+

+ Add to every element that should be included in the pdf-tab.pdf the + attribute wholesite="true" + +

+
+
+<sample-wiki label="Wiki page" href="wiki-sample.html"
+  description="wiki-sample" wholesite="true"/>
+      
+
+
Note
+
+ This attribute will be inherited by all children of the element. Do not + use it in the parent element that contains the +<whole_foosite href="pdf-tab.html" label="pdf-tab" /> + as the child (will cause a stack overflow if you + do)!!! +
+
+ +

Explanation of the operation

+

+ Line 4 of our example +
+ + +<map:parameter name="include" value="//*[@wholesite='true']"/> + looks at your site.xml and will match every element containing + the wholesite="true" attribute. For example, to use the + "samples" tab ... +

+
+
+...
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+...
+</samples>
+...
+      
+

+ It matches all of the elements that contain + wholesite="true" (in our example +<samples> + and its "children") for the content of the pdf file to be + generated. +

+
+ 
+<samples label="Samples" href="samples/" tab="samples" wholesite="true">
+ <sample2 label="Static content" href="sample2.html"      
+   description="More Samples" wholesite='false'/>
+ <sample-wiki label="Wiki page" href="wiki-sample.html"      
+   description="wiki-sample" />
+ <sample-ihtml label="ihtml page" href="ihtml-sample.html"      
+   description="Test iHTML page" />
+</samples> 
+      
+

+ This example shows that you can as well exclude site(s) from the + aggregation by using the wholesite="false" attribute. This + attribute will be as well inherited by all children of the element. +

+

+ Line 8 defines the title of the pdf file by taking the content of the + project-name variable in skinconf.xml and adding some funny + text: +
+ + +<map:parameter name="title" value="{conf:project-name}: Still My Foo Site"/> + + +

+
+ +

Feedback and further development of this How-To

+
+

+ Please provide feedback about this document via the + mailing lists. +

+

+ In the future, this ability will probably be incorporated into the main + Forrest process. +

+
+
+ +
 
+
+ + + Propchange: forrest/site/docs_0_90/howto/howto-pdf-tab.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_90/howto/howto-pdf-tab.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/howto-pdf-tab.pdf?view=auto&rev=529910 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_90/howto/howto-pdf-tab.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_90/howto/index.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/index.html?view=auto&rev=529910 ============================================================================== --- forrest/site/docs_0_90/howto/index.html (added) +++ forrest/site/docs_0_90/howto/index.html Wed Apr 18 01:10:58 2007 @@ -0,0 +1,443 @@ + + + + + + + +Overview of the How-To documents (v0.9-dev) + + + + + + + + + +
+ +
+apache > forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+ +
Font size: +   +   +   +
+

Overview of the How-To documents

+
+ This is documentation for development version v0.9-dev + (More)
+ + + +

Forrest Site and Documentation

+
+
    + +
  • +How to write a How-To + - Provides instructions about writing documents. Please copy this + file to serve as a template for your own document. +
  • + +
  • +Generate an ASF mirrors page using interactive web form + - include html form elements + into a forrest-generated html page. For example, this enables building + automated download mirror pages for ASF project websites. + Also shows how to process "extra" documents, i.e. that have no links + from anywhere in the site. +
  • + +
+
+ + +

Using and developing with Forrest

+
+

+ You will soon see that there is not much distinction between users and + developers. +

+ +
+ + +

Extending Forrest

+
+
    + +
  • +How to create a Plugin for Forrest + - Describes how to write a plugin to add new input or output document + formats, or to modify the default behaviour of Forrest
  • + +
+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_90/howto/index.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_90/howto/index.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/index.pdf?view=auto&rev=529910 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_90/howto/index.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf Added: forrest/site/docs_0_90/howto/multi/howto-multi.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/multi/howto-multi.html?view=auto&rev=529910 ============================================================================== --- forrest/site/docs_0_90/howto/multi/howto-multi.html (added) +++ forrest/site/docs_0_90/howto/multi/howto-multi.html Wed Apr 18 01:10:58 2007 @@ -0,0 +1,484 @@ + + + + + + + +Example of a multi-page how-to (v0.9-dev) + + + + + + + + + +
+ +
+apache > forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+ +
Font size: +   +   +   +
+

Example of a multi-page how-to

+
+ This is the shell of a multi-page how-to. Add your own content. +
+
+ This is documentation for development version v0.9-dev + (More)
+ + +

Intended audience

+
+

+ Describe the audience here. +

+
+ +

Purpose

+
+

+ Explain the purpose of the howto here. +

+
+ +

Prerequisites

+
+

+ Configuration requirements: +

+
    + +
  • This.
  • + +
  • That.
  • + +
+

+ Requisite skills: +

+
    + +
  • These.
  • + +
  • Those.
  • + +
+
+ +

Various Steps

+
+

+ After this brief introductory paragraph, the steps are described in + separate documents: +

+ +
+ +

Real World Extension

+
+

+ Briefly describe some relevant extensions that go beyond these basics. +

+
+ +

Tips

+
+

+ If you have a problem running the example, then you can try the following + tips: +

+
    + +
  • Tip #1
  • + +
  • Tip #2
  • + +
+
+ +

Related Resources

+
+

+ Cocoon resources: +

+ +
+ +

Feedback

+
+

+ If you find any faults in this How-to or can see any improvements, please + contact the project mail lists with + them. +

+
+
+ +
 
+
+ + + Propchange: forrest/site/docs_0_90/howto/multi/howto-multi.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_90/howto/multi/howto-multi.pdf URL: http://svn.apache.org/viewvc/forrest/site/docs_0_90/howto/multi/howto-multi.pdf?view=auto&rev=529910 ============================================================================== Binary file - no diff available. Propchange: forrest/site/docs_0_90/howto/multi/howto-multi.pdf ------------------------------------------------------------------------------ svn:mime-type = application/pdf