forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rgard...@apache.org
Subject svn commit: rev 65601 - in forrest/trunk/docs-author/content/xdocs: . howto plugins
Date Sun, 14 Nov 2004 16:23:06 GMT
Author: rgardler
Date: Sun Nov 14 08:23:05 2004
New Revision: 65601

Added:
   forrest/trunk/docs-author/content/xdocs/plugins/
   forrest/trunk/docs-author/content/xdocs/plugins/usingPlugins.xml
      - copied, changed from rev 65595, forrest/trunk/docs-author/content/xdocs/plugins.xml
Removed:
   forrest/trunk/docs-author/content/xdocs/plugins.xml
Modified:
   forrest/trunk/docs-author/content/xdocs/howto/index.xml
   forrest/trunk/docs-author/content/xdocs/site.xml
Log:
split plugin documentation between user and developer topics

Modified: forrest/trunk/docs-author/content/xdocs/howto/index.xml
==============================================================================
--- forrest/trunk/docs-author/content/xdocs/howto/index.xml	(original)
+++ forrest/trunk/docs-author/content/xdocs/howto/index.xml	Sun Nov 14 08:23:05 2004
@@ -23,30 +23,48 @@
   </header>
 
   <body>
-    <ul>
-      <li><link href="site:howto/write-howto">How to write a How-To</link>
-        - Provides instructions about writing documents. Please copy this
-        file to serve as a template for your own document.
-      </li>
-      <li><link href="site:howto/asf-mirror">Generate an ASF mirrors page using
interactive web form</link>
-        - Use ihtml (interpreted html) to include html form elements
-        into a forrest-generated html page. For example, this enables building
-        automated download mirror pages for ASF project websites.
-      </li>
-      <li><link href="site:howto/pdf-tab">How to create a PDF document for each
tab</link>
-        - Describes the generation of a PDF document for each
-        group of documents that is defined by a tab.
-      </li>
-      <li><link href="site:howto/editcss">How to edit Forrest's CSS in a WYSIWYG
fashion</link>
-        - Describes the use of Mozilla Firebird and the free EditCSS-Plugin to 
-        customize your Forrest design in a WYSIWYG-way.
-      </li>
-      <li><link href="site:howto/corner-css">How to modify the color of generated
corner images</link>
-        - Describes the use of CSS values from the skinconf.xml configuration
-        file to change the color of the corner images to be suitable for
-        your own skin colors. Advanced use explains editing the *.css too.
-      </li>
-    </ul>
+    <section>
+      <title>Forrest Site and Documentation</title>
+      <ul>
+        <li><link href="site:howto/write-howto">How to write a How-To</link>
+          - Provides instructions about writing documents. Please copy this
+          file to serve as a template for your own document.
+        </li>
+        <li><link href="site:howto/asf-mirror">Generate an ASF mirrors page using
interactive web form</link>
+          - Use ihtml (interpreted html) to include html form elements
+          into a forrest-generated html page. For example, this enables building
+          automated download mirror pages for ASF project websites.
+        </li>
+      </ul>
+    </section>
+    
+    <section>
+      <title>Using Forrest</title>
+      <ul>
+        <li><link href="site:howto/pdf-tab">How to create a PDF document for
each tab</link>
+          - Describes the generation of a PDF document for each
+          group of documents that is defined by a tab.
+        </li>
+        <li><link href="site:howto/editcss">How to edit Forrest's CSS in a WYSIWYG
fashion</link>
+          - Describes the use of Mozilla Firebird and the free EditCSS-Plugin to 
+          customize your Forrest design in a WYSIWYG-way.
+        </li>
+        <li><link href="site:howto/corner-css">How to modify the color of generated
corner images</link>
+          - Describes the use of CSS values from the skinconf.xml configuration
+          file to change the color of the corner images to be suitable for
+          your own skin colors. Advanced use explains editing the *.css too.
+        </li>
+      </ul>
+    </section>
+    
+    <section>
+      <title>Extending Forrest</title>
+      <ul>
+        <li><link href="site:howto/buildPlugin">How to create a Plugin for Forrest</link>
+          - Describes how to write a plugin to add new input or output document
+          formats, or to modify the default behaviour of Forrest</li>
+      </ul>
+    </section>
   </body>
 
 </document>

Copied: forrest/trunk/docs-author/content/xdocs/plugins/usingPlugins.xml (from rev 65595,
forrest/trunk/docs-author/content/xdocs/plugins.xml)
==============================================================================
--- forrest/trunk/docs-author/content/xdocs/plugins.xml	(original)
+++ forrest/trunk/docs-author/content/xdocs/plugins/usingPlugins.xml	Sun Nov 14 08:23:05 2004
@@ -80,168 +80,15 @@
           it is recomended that you override this value in your projects
           <code>forrest.properties</code> file.</p>
         </section>
-    </section>
-    
-  </section>
-    
-    <section>
-      <title>What is a Forrest Plugin?</title>
-
-      <p>A Forrest plugin is a set of resources and configuration files that 
-      extend the functionality of Forrest. They will typically consist of a 
-      sitemap, zero or more stylesheets and zero or more schema's.</p>
-
-      <p>The plugins sitemap is mounted by Forrest's sitemap after the project 
-      specific sitemap but before the Forrest default matchers. This allows 
-      individual projects to override/extend functionality provided in either 
-      a plugin or Forrest whilst plugins are only able to override/extend the 
-      default Forrest behaviour.</p>
-
-      <p>Forrest is easily extensible through the existing sitemap.xmap files, 
-      however the more features we add, the more complex the sitemap becomes. It 
-      is already quite difficult to understand the default sitemap.xmap files, 
-      and this will only get worse as new features find their way into the 
-      core.</p>
-
-      <p>By adopting a plugin model we can keep the core of Forrest tightly 
-      focused on the basic functionality, whilst still facilitating extensions 
-      to suit individual projects needs.</p>
-    
-      <section>
-        <title>An Example Plugin</title>
-  
-        <p>In order to fully understand the applicability of Forrest Plugins we 
-        will consider an extension to the way in which Forrest defines the 
-        structure of the site. By default Forrest uses a site.xml file to 
-        define navigation through the site and a tabs.xml file to define the 
-        tabs across the top of the page. But what if we want to use a different
-        file to describe site structure? For example, what if we want to use an
-        IMS Manifest file from the SCORM content package standards 
-        (http://www.adlnet.org/).</p>
-  
-        <p>An IMS Manifest file describes the structure of a site. It is also 
-        possible to define a set of rules for extracting tab information from 
-        such a file. Consequently, it is possible to use an IMSManifest file to 
-        create Forrest's site.xml and tabs.xml files. The advantage would be that
-        we can then use SCORM compliant content objects within Forrest.</p>
-  
-        <p>Unfortunately, IMS Manifests are much more complex than site.xml and 
-        tabs.xml files. Therefore, not all users will want to use them. Adding 
-        the functionality as an optional plugin seems to be the ideal 
-        solution.</p>
       </section>
     </section>
-
-    <section>
-      <title>What Does a Forrest Plugin Look Like?</title>
-
-      <p>Plugins will need to conform to a specified directory structure. 
-      This mirrors the default forrest directory structure:</p>
-
-<source>
-[plugin_name]
-  |
-  |-- config files (xmap, skinconf etc.)
-  |
-  |-- resources
-      |
-      |-- schema
-      |   |
-      |   |-- catalog.xcat
-      |   |
-      |   |--DTD (dtd's etc.)
-      |
-      |-- stylesheets (xsl's etc.)
-</source>
-  
+    
     <section>
-      <title>The IMS Manifest Plugin</title>
-
-      <p>If we consider the IMS Manifest Plugin described above we see that we
-      will need the following files and directory structure:</p>
-
-     
-<source>
-IMSManifest
-  |
-  |-- sitemap.xmap
-  |
-  |-- resources
-      |
-      |-- stylesheets
-                    |
-                    |- imsmanifest2site.xsl
-                    |- imsmanifest2tabs.xsl
-                    |- pathutils.xsl
-                    |- repositoryUtils.xsl
-</source>
-
-      <p>The sitemap.xmap file will override the default behaviour for the 
-      navigation generation matchers in Forrest, for example, it contains 
-      a matcher as follows:</p>
-
-<source><![CDATA[
-<map:match pattern="abs-menulinks">
-  <map:select type="exists">
-    <map:when test="{project:content.xdocs}imsmanifest.xml">
-       <map:generate src="{project:content.xdocs}imsmanifest.xml" />
-       <map:transform src="{forrest:plugins}/IMSManifest/resources/stylesheets/imsmanifest2site.xsl"/>
-       <map:transform src="{forrest:stylesheets}/absolutize-linkmap.xsl" />
-       <map:transform src="{forrest:stylesheets}/site2site-normalizetabs.xsl" />
-     <map:serialize type="xml"/>
-   </map:when>
-   <map:when test="{project:content.xdocs}site.xml">
-      <map:generate src="{project:content.xdocs}site.xml" />
-      <map:transform src="{forrest:stylesheets}/absolutize-linkmap.xsl" />
-      <map:transform src="{forrest:stylesheets}/site2site-normalizetabs.xsl" />
-      <map:transform src="{forrest:stylesheets}/normalizehrefs.xsl"/>
-    <map:serialize type="xml"/>
-  </map:when>
-  </map:select>
-</map:match>
-]]></source>
-
-      <note>Note that this matcher will default to the behaviour provided by 
-      Forrest if there is no imsmanifest.xml file present in the project.
-      At present it is necessary to copy this default behaviour from the original
-      Forrest *.xmap files. We hope to improve on this in the future.</note>
-    </section>
-  </section>
-
-  <section>
-    <title>How does Installation work?</title>
-    <p>When Forrest installs a plugin it downloads a zip of the plugin code and 
-    extracts it into the <code>plugins</code> directory of Forrest and an entry
is made 
-    in <code>src/plugins/sitemap.xmap</code>. For example, installing the 
-    IMSManifest plugin described above will result in the following entry 
-    being added to the plugin sitemap:</p>
-
-  <source><![CDATA[
-<map:select type="exists">
-  <map:when test="{forrest:plugins}/IMSManifest/sitemap.xmap">
-    <map:mount uri-prefix="" 
-      src="{forrest:plugins}/IMSManifest/sitemap.xmap" 
-      check-reload="yes" 
-      pass-through="true"/>
-  </map:when>
-</map:select>
-  ]]></source>
-  
-      <p>Installed plugins are managed by the
-      FORREST_INSTALL_DIR/plugins/sitemap.xmap file. This file is mounted
-      by the main Forrest sitemap with the following code:</p>
-  
-  <source><![CDATA[
-        <map:pipeline internal-only="false">
-           <map:mount uri-prefix=""
-                      src="{forrest:plugins}/sitemap.xmap"
-                      check-reload="yes"
-                      pass-through="true"/>
-        </map:pipeline>
-  ]]></source>
-      
-      <note>The plugin sitemap.xmap file is automatically managed by Forrest, the 
-      end user need never edit this file.</note>
+      <title>Further Reading</title>
+      <ul>
+        <li><a href="site:documentation/developers/pluginInfrastructure">Plugin
Infrastrucuture</a></li>
+        <li><a href="site:howto/buildPlugin">How to build a Plugin</a></li>
+      </ul>
     </section>
   </body>
 </document>

Modified: forrest/trunk/docs-author/content/xdocs/site.xml
==============================================================================
--- forrest/trunk/docs-author/content/xdocs/site.xml	(original)
+++ forrest/trunk/docs-author/content/xdocs/site.xml	Sun Nov 14 08:23:05 2004
@@ -42,7 +42,7 @@
     <skins label="Default Skins" href="skins.html"/>
     <skin-package label="Skin Packages" href="skin-package.html"/>
     <skin-leather label="Leather-skin" href="leather.html"/>
-    <plugins label="Plugins" href="plugins.html"/>
+    <plugins label="Plugins" href="plugins/usingPlugins.html"/>
     <!--
     <quick-xml label="XML Guide" href="quick-xml.html"/>
     -->
@@ -60,6 +60,7 @@
         <forrest_xmap href="#forrest_xmap"/>
       </sitemap-ref>
       <project-sitemap label="Project sitemap" href="project-sitemap.html"/>
+      <pluginInfrastructure label="Plugin Infrastructure" href="plugins/pluginInfrastructure.html"/>
       <cap label="Sourcetype Action" href="cap.html"/>
     </developers>
     
@@ -110,6 +111,7 @@
     <pdf-tab label="Create tab PDF" href="howto-pdf-tab.html"/>
     <editcss label="Edit CSS (WYSIWYG)" href="howto-editcss.html"/>
     <corner-css label="CSS corner SVG" href="howto-corner-images.html"/>
+    <buildPlugin label="Build a Plugin" href="howto-buildPlugin.html"/>
   </howto>
 
   <!-- Uncomment this if we want aggregate HTML/PDFs for this site 

Mime
View raw message