Added: forrest/site/docs_0_100/searching.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/searching.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/searching.html (added) +++ forrest/site/docs_0_100/searching.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,501 @@ + + + + + + + +Searching Forrest-built documentation (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Searching Forrest-built documentation

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

+ Forrest provides you with two distinct options for making your + documentation available through full-text search: +

+ + + +

+ Both options have their advantages and disadvantages. The purpose of this + document is to outline them, and to help you make a choice. This document + also tells you how to disable full-text search completely, if you so + choose. +

+ + +

Google SiteSearch

+
+

+ Forrest provides a simple interface to the Google search engine. It + invokes Google Advanced Search and limits the search scope to the domain + of your choice. Since the actual search functionality is implemented on + Google's end, you do not need any additional capability on your Forrest + server (which may well be a simple static web server serving content + generated with forrest site). +

+

+ To use Google SiteSearch in your Forrest application, open your + skinconf.xml file. By default this file is in the + src/documentation subdirectory of your Forrest repository + root. Find the <search> element; it should be near + the top of the file. If the element does not exist, create it below the + <skinconfig> opening tag. If there is any attribute + named provider, remove it. The element should look similar + to this: +

+
+<search name="MyProject"
+	domain="myproject.com"/>
+      
+

+ Then, build your Forrest documentation and open it using your favorite + web browser. You are now invited to peruse the search box (most skins + render this in the top-right corner). Google's search results will be + displayed in a new browser window. +

+

+ Needless to say, for this to work your content must be accessible to + Google's indexing robot. It can't be stored on a server which is only + locally accessible, or which requires authentication. In addition, the + content index is created and updated at a time of Google's choosing. + However, the search is fast and search precision is usually excellent. + So if your Forrest content is placed on a busy, popular public web + server, Google search is probably the best choice. +

+
+ + +

Lucene search

+
+

+ Lucene is a high-performance, full-text search engine built entirely in + Java. To use Lucene-based search with your Forrest documentation, you + will need to run Forrest in a Java servlet environment (such as Tomcat + or Jetty). Lucene-based searching will not work in a static site + generated with the 'forrest site' command. +

+

+ In order to enable Lucene-based full-text search in your Forrest + application, you must first edit your skinconf.xml file. + Locate the <search> element. If the element does not + exist, insert it right underneath the <skinconfig> + opening tag. Add an attribute named provider with a value + of lucene, so that the element looks similar to this: +

+
+<search name="MyProject" domain="myproject.com"
+	provider="lucene"/>
+      
+

+ Next, create and run your Forrest webapp. This may mean simply invoking + forrest run, or building and bundling a servlet webapp + (with forrest webapp), and then deploying it to your + servlet container. +

+

+ You can now build a Lucene search index by pointing your web browser at + http://localhost:8888/lucene-update.html. This generates + the search index and provides some information about the index + generation process. +

+
+
Note
+
+ You may have to substitute a different hostname, port, or path, + depending on your configuration. The path mentioned here reflects + Forrest's default settings when invoked as forrest run. +
+
+

+ Now you can utilize the full-text search box, located in the top-right + corner of the rendered Forrest pages. Search results will be displayed + in the same browser window and will look remarkably similar to the rest + of your Forrest documents. +

+

+ Unlike with Google SiteSearch, the indexing information retrieved by + Lucene is stored on your own server, access to which you may limit to + users in your own organization. Likewise, you may update or recreate the + Lucene index at any time and at your own discretion. So if you aren't + making your Forrest-built documentation publicly available, and you're + able to run Forrest on a Java-enabled web server, Lucene search is + probably right for you. +

+
+ + +

Disabling full-text search

+
+

+ If you are convinced your users don't need any full-text search + capability whatsoever, you may disallow displaying the search box + entirely. You may also wish to do so if you're keeping Forrest-built + content on a restricted server (meaning you can't use Google), while at + the same time not having any usable servlet-capable web server at your + disposal (meaning you can't use Lucene, either). +

+

+ To disable full-text search completely, open the + skinconf.xml file and remove (or comment out) the entire + <search> element. +

+
+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_100/searching.html ------------------------------------------------------------------------------ svn:eol-style = native Added: forrest/site/docs_0_100/sitemap-explain.html URL: http://svn.apache.org/viewvc/forrest/site/docs_0_100/sitemap-explain.html?rev=1068306&view=auto ============================================================================== --- forrest/site/docs_0_100/sitemap-explain.html (added) +++ forrest/site/docs_0_100/sitemap-explain.html Tue Feb 8 09:44:46 2011 @@ -0,0 +1,538 @@ + + + + + + + +Cocoon sitemap explained (v0.10-dev) + + + + + + + + + +
+ +
+Apache Software Foundation > Apache Forrest +
+ +
+ + + + + + + + + + + + +
+
+
+
+ + + + +
+ +
+ +   +
+ + + + + +
+
Font size: +   +   +   +
+

Cocoon sitemap explained

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

+ This document is intended to be a concise explanation of the Apache Cocoon + Sitemap and its use in Apache Forrest. This + is a worked example showing the automatically generated Table of Contents. + Please follow the various sitemaps as we explain. +

+ +
+cd $FORREST_HOME/site-author
+forrest run
+
+ +

+ In a separate browser window, open + localhost:8888/linkmap.html to see + the generated Table of Contents. This has been transformed from the + site.xml navigation configuration to show the layout of the whole site as + a ToC. +

+ +

+ Cocoon consults the sitemaps to find out how to process the + linkmap.html request. +

+ +

+ The main sitemap is $FORREST_HOME/main/webapp/sitemap.xmap + and if the match is not found there then other sitemaps are consulted. The + first match wins. Various sitemaps are responsible for different types of + processing and there are also sitemaps in the many plugins. +

+ +

+ So let us see how linkmap.html is handled. +

+ +

+ Open $FORREST_HOME/main/webapp/sitemap.xmap in another + window. Search for "linkmap" to find the following snippet: +

+ +
+<map:match pattern="linkmap.*">
+  <map:mount uri-prefix="" src="linkmap.xmap" check-reload="yes" />
+</map:match>
+    
+ +

+ Cocoon has passed through the other potential matches earlier in the + sitemap and now does further handling via the linkmap.xmap + sitemap. +

+ +

+ Before going any further, it is necessary to understand the "**" and "*" + pattern matching and replacements. See the email thread: "Re: explain + sitemap matches and pass parameters to transformers" + FOR-874. +

+ +

+ Okay we will skip some explanation of processing. At this stage we are + only concerned with generating the internal xml. Later steps of processing + will transform that into the final html output and adorn it with + navigation menus and headers, etc. This is your main aim for most of your + sitemap work for input formats: handle the incoming requests, and + transform into the standard internal xml format. Then Forrest + automatically does the rest. +

+ +

+ In another browser window, open localhost:8888/linkmap.xml to + see the internal xml format. +

+ +

+ Open $FORREST_HOME/main/webapp/linkmap.xmap sitemap. Move to + the "map:pipeline" section. +

+ +

+ A digression: The first match is not triggered because our request is for + linkmap.xml and this match handles + linkmap.source.xml to essentially re-direct it to + linkmap.xml instead. That is what the cocoon:// means: + generate it via a different request within this sitemap. Try + localhost:8888/linkmap.source.xml to see the exact same + internal xml format. +

+ +

+ The second match exactly meets our pattern linkmap.xml + +

+ +
+<map:match pattern="linkmap.xml">
+  <map:generate src="cocoon://abs-linkmap" />
+  <map:transform src="{lm:transform.linkmap.document}"/>
+  <map:serialize type="xml" />
+</map:match>
+    
+ +

+ As with all pipelines, it starts with a generator to commence the xml + stream, then transforms it with a single transformer (there could be + multiple sequential transformers) and finally the serializer component. + Here it is: +

+ +

+ The generator is not simply reading an xml file. It produces the xml via a + different part of this sitemap. Let us explain that later and assume for + now that it produces the xml from your site.xml file. +

+ +

+ Move on to the transformer. It transforms the xml obtained from the + site.xml into the internal document xml format using an XSLT stylesheet. + The locationmap reference defines the source for that stylesheet: + "lm:transform.linkmap.document" is evaluated by the Locationmap to be the + main/webapp/resources/stylesheets/linkmap-to-document.xsl + stylesheet. See the Locationmap + documentation for explanation. +

+ +

+ Now let us get back to that new request for "abs-linkmap". This is used a + number of times within this sitemap, hence it is its own pipeline. As + usual it starts with a generator, then a transformer, then a serializer. +

+ +

+ Again the generator is sent to some other part of the sitemap hierarchy, + because this request is needed by many other parts of the system beyond + just this linkmap handling. You see that it is not matched within this + linkmap.xmap sitemap. Go to the main sitemap.xmap and search for + "site.navigation.links.xml" where you find the match that handles this by + looking for various Locationmap definitions to find and transform the + site.xml file. +

+ +

+ Don't get lost, come back to the linkmap.xmap sitemap. +

+ +

+ Following this generator, the transformer turns the links into absolute + references. This is then serialized as xml to finish this "abs-linkmap" + match which is the end of the generator in our main match. +

+ +

+ A developer's trick will help to understand what is happening. Edit the + linkmap.xmap to comment-out the transformer ... +

+ +
+
+      <map:match pattern="linkmap.xml">
+        <map:generate src="cocoon://abs-linkmap" />
+<!--
+        <map:transform src="{lm:transform.linkmap.document}"/>
+-->
+        <map:serialize type="xml" />
+      </map:match>
+
+    
+ +

+ Browser localhost:8888/linkmap.xml to see the result of the + "abs-linkmap" generation before it is transformed into the internal + document xml. +

+ +

+ So now you understand some of the power of sitemaps. +

+ +

+ A basic understanding of Cocoon's pipelines and their components will help + you to realise the true power. You should know about matchers, generators, + transformers and serializers and have a rough idea how they work together + in a pipeline. A good place to start learning about Cocoon is + Understanding + Apache Cocoon. The Forrest Sitemap + Reference will also be helpful. +

+ +
+ +
 
+
+ + + Propchange: forrest/site/docs_0_100/sitemap-explain.html ------------------------------------------------------------------------------ svn:eol-style = native