You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Ferdinand Soethe <sa...@soethe.net> on 2005/03/03 12:13:25 UTC

Questions on extending the OOwriter-PlugIn to support HowTos

Hi Ross,

I'm trying to extend your OOWriter-Plugin to support HowTos and
so far it looks quite easy to do.

1. Changed OpenOffice-common2Forrest to insert some HowTo Header Info
   by adding the quoted sections:

  <!--+
      | start transforming 
      +-->
  <xsl:template match="/">
    <document>
      <header>
        <title>
          <xsl:choose>
            <xsl:when test="/office:document/office:meta/dc:title = '' or not(/office:document/office:meta/dc:title)">
              <xsl:value-of select="$filename"/>
            </xsl:when>
            <xsl:otherwise>
              <xsl:value-of select="/office:document/office:meta/dc:title"/>
            </xsl:otherwise>
          </xsl:choose>
        </title>

>         <!-- Abstract is required field in HowTos, so always create it and fill with description field  -->
>         <xsl:choose>
>                 <abstract>
>                         <xsl:when test="/office:document/office:meta/dc:description = '' or not(/office:document/office:meta/dc:description)">
>                         </xsl:when>     
>                         <xsl:otherwise>
>                         <xsl:value-of select="/office:document/office:meta/dc:description"/>
>                 </xsl:otherwise>
>                 </abstract>
>         </xsl:choose> 
>         
>         <!-- last modified date -->
>         <last-modified-content-date date="format-dateTime({/office:document/office:meta/dc:date}, '[Y]-[M]-[D]')"/>


        <xsl:call-template name="style"/>
      </header>
      <xsl:apply-templates select="//office:body"/>
    </document>
  </xsl:template>
  
  <!--+
      | create the body 
      +-->
  <xsl:template match="office:body">
    <body>

       <!-- This is special for HowTo-Documents. Will make this
            conditonal as soon as it is working  -->
>      <header>
>         <title>
>           <xsl:choose>
>             <xsl:when test="/office:document/office:meta/dc:title = '' or not(/office:document/office:meta/dc:title)">
>               <xsl:value-of select="$filename"/>
>             </xsl:when>
>             <xsl:otherwise>
>               <xsl:value-of select="/office:document/office:meta/dc:title"/>
>             </xsl:otherwise>
>           </xsl:choose>
>         </title>
>
>         <!-- Abstract is required field in HowTos, so always create it and fill with description field  -->
>         <xsl:choose>
>                 <section id="Overview">
>                         <title>Overview</title>
>                         <p>
>                         <xsl:when test="/office:document/office:meta/dc:description = '' or not(/office:document/office:meta/dc:description)">
>                         </xsl:when>
>                         <xsl:otherwise>
>                         <xsl:value-of select="/office:document/office:meta/dc:description"/>
>                 </xsl:otherwise>
>                         </p>
>                 </section>
>         </xsl:choose>
>       </header>

    
      <xsl:apply-templates select="key('rootChildren', generate-id())"/>
      <xsl:apply-templates select="text:h[@text:level='1']"/>      
    </body>
  </xsl:template>


2. I used and tested the OO-Plugin before modifying the file in the
   plug-ins-dir then changed above file and re-ran Forrest

   Funny thing is, nothing changes. It still compiles w/o errors, but
   none of the elements show. Tried and called the document.xml and
   it's not there either.

 Do I need to somehow reload plugins after I've changed
 stylesheets or where is my mistake here?


--
Ferdinand Soethe



Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
>>        <!-- Abstract is required field in HowTos, so always create it and fill with description field  -->
>>        <xsl:choose>
>>                <abstract>
>>                        <xsl:when test="/office:document/office:meta/dc:description = '' or not(/office:document/office:meta/dc:description)">
>>                        </xsl:when>     
>>                        <xsl:otherwise>
>>                        <xsl:value-of select="/office:document/office:meta/dc:description"/>
>>                </xsl:otherwise>
>>                </abstract>
>>        </xsl:choose> 

This will always put an abstract element in regardless of whether the it 
is needed. This may be your intention since this would still be legal 
XDoc and it makes sense. However, it is confusing to read because of the 
way you have nested the elements. Would read better (at least for me) as:

<abstract>
   <xsl:choose>
     ...
   </xsl:choose>
</abstract>

In addition the choice is not really necessary. If there is no 
dc:description element then the result of the <xsl:value-of...> would be 
empty anyway, so you can simply do:

<abstract>
     <xsl:value-of select="/office:document/office:meta/dc:description"/>
</abstract>

> 2. I used and tested the OO-Plugin before modifying the file in the
>    plug-ins-dir then changed above file and re-ran Forrest
> 
>    Funny thing is, nothing changes. It still compiles w/o errors, but
>    none of the elements show. Tried and called the document.xml and
>    it's not there either.

See other reply from Johannes.

Ross

Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
> 
> Ross Gardler wrote:
> 
> RG> This is because if you install the forthcoming binary version of 0.7,
> RG> you won't get the plugins, only the core, plugins are downloaded as and
> RG> when they are needed.
> 
> Will they still be cached somewhere or would that mean that I need a
> live connection to the plug-in server each time I compile my Forrest?

The are cached locally.

Ross

Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ferdinand Soethe <sa...@soethe.net>.

Ross Gardler wrote:

RG> This is because if you install the forthcoming binary version of 0.7,
RG> you won't get the plugins, only the core, plugins are downloaded as and
RG> when they are needed.

Will they still be cached somewhere or would that mean that I need a
live connection to the plug-in server each time I compile my Forrest?

--
Ferdinand Soethe



Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ferdinand Soethe <sa...@soethe.net>.

Ross Gardler wrote:
RG> Ferdinand Soethe wrote:
>> 
>> RG> Can I ask that you provide a patch for this rather than a new document.
>> RG> It makes it much easier to get it into SVN that way.
>> 
>> Done.

RG> Thanks, I'll apply soon.

Interesting behavior with OOwriter templates and OO 1.14.

If you have a template called howto.stw and open it with writer, it
will correctly recognize the template and open it as a new document
based on that template. It will not however show the name of that
template in the meta data.

Same if you place that template in the templates directory and use it
to create a new document.

If however you place a file called howto.sxw (a document) in the
templates directory, you can create a new document based on it and the new
document will have the meta data in a field called

<meta:template
              xlink:type="simple"
              xlink:actuate="onRequest"
              xlink:role="template"
              xlink:href="file:///C:/Programme/OpenOffice.org1.1.4/user/template/fromdocument.sxw"
              xlink:title="OpenOffice.org Writer HowTo - Sample"
              meta:date="2005-03-05T20:08:15"/>


So I guess I'll check for that info to distinguish between templates
even though this means that the templates have to be documents.

--
Ferdinand Soethe



Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ferdinand Soethe <sa...@soethe.net>.

Thorsten Scherler wrote:

>> However doing a test create patch, I found the patchfile to contain
>> absolute pathnames once again:
>> 
>> RG> ---
>> P:/forrest/plugins/org.apache.forrest.plugin.OpenOffice.org/resources/stylesheets/openoffice-common2forrest.xsl
>> (revision 156284)
>> RG> +++
>> P:/forrest/plugins/org.apache.forrest.plugin.OpenOffice.org/resources/stylesheets/openoffice-common2forrest.xsl
>> (working copy)
>> 
>> So does this not matter when you apply that patch later on? I figured
>> relative pathnames starting from root of my repository where needed to
>> make the patchfiles universally applicable.
>> 

TS> Yeah, you are right it is better to do something like (linux env)

svn diff . >>patch.txt

TS> in the shell of your choice.

Well I realize that. But that was exactly what I was trying to
automate with Eclipse when my original question was:

TS> Some other question: (Of course) I'm trying to automate patch creation
TS> as an external tool in eclipse. My problem is that the
TS> ${resource_name}-variable I use to pass the name of the file relative
TS> to the Forrest dir will use Eclipses Folder-Names instead of the
TS> underlying dir names. So when the project name is different from the
TS> folder name where the project resides this doesn't work.
TS> 
TS> Unfortunately I found not other variable that does it and absolute
TS> pathnames or at all would make the patchfile useless for
TS> your processes, right?

So the conclusion is the Eclipse can't do it and because Eclipse
can't, subclipse can't either. So their is no comfi solution to my
problem, right?

Thanks everybody anyway.

--
Ferdinand Soethe



Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Thorsten Scherler <th...@apache.org>.
On Sat, 2005-03-05 at 23:59 +0100, Ferdinand Soethe wrote:
> >> Some other question: (Of course) I'm trying to automate patch creation
> >> as an external tool in eclipse.
> 
> RG> Much better is to install the subclipse plugin, right click on the files
> RG> or directories you want to create the patch of and select Team > create
> RG> patch.
> 
> Thanks! Installed that and found a whole new world in my Navigator. I
> really like Eclipse!
> 
> However doing a test create patch, I found the patchfile to contain
> absolute pathnames once again:
> 
> RG> --- P:/forrest/plugins/org.apache.forrest.plugin.OpenOffice.org/resources/stylesheets/openoffice-common2forrest.xsl (revision 156284)
> RG> +++ P:/forrest/plugins/org.apache.forrest.plugin.OpenOffice.org/resources/stylesheets/openoffice-common2forrest.xsl (working copy)
> 
> So does this not matter when you apply that patch later on? I figured
> relative pathnames starting from root of my repository where needed to
> make the patchfiles universally applicable.
> 

Yeah, you are right it is better to do something like (linux env)
svn diff . >patch.txt

in the shell of your choice.

salu2
thorsten
> --
> Ferdinand Soethe
> 
> 
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)


Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ferdinand Soethe <sa...@soethe.net>.
>> Some other question: (Of course) I'm trying to automate patch creation
>> as an external tool in eclipse.

RG> Much better is to install the subclipse plugin, right click on the files
RG> or directories you want to create the patch of and select Team > create
RG> patch.

Thanks! Installed that and found a whole new world in my Navigator. I
really like Eclipse!

However doing a test create patch, I found the patchfile to contain
absolute pathnames once again:

RG> --- P:/forrest/plugins/org.apache.forrest.plugin.OpenOffice.org/resources/stylesheets/openoffice-common2forrest.xsl (revision 156284)
RG> +++ P:/forrest/plugins/org.apache.forrest.plugin.OpenOffice.org/resources/stylesheets/openoffice-common2forrest.xsl (working copy)

So does this not matter when you apply that patch later on? I figured
relative pathnames starting from root of my repository where needed to
make the patchfiles universally applicable.

--
Ferdinand Soethe



Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
> 
> RG> Can I ask that you provide a patch for this rather than a new document.
> RG> It makes it much easier to get it into SVN that way.
> 
> Done.

Thanks, I'll apply soon.

> Some other question: (Of course) I'm trying to automate patch creation
> as an external tool in eclipse.

Much better is to install the subclipse plugin, right click on the files 
or directories you want to create the patch of and select Team > create 
patch.

http://www.eclipse-plugins.info/eclipse/search.jsp?query=subclipse

Ross

Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ferdinand Soethe <sa...@soethe.net>.

RG> Can I ask that you provide a patch for this rather than a new document.
RG> It makes it much easier to get it into SVN that way.

Done.

Some other question: (Of course) I'm trying to automate patch creation
as an external tool in eclipse. My problem is that the
${resource_name}-variable I use to pass the name of the file relative
to the Forrest dir will use Eclipses Folder-Names instead of the
underlying dir names. So when the project name is different from the
folder name where the project resides this doesn't work.

Unfortunately I found not other variable that does it and absolute
pathnames or at all would make the patchfile useless for
your processes, right?





--
Ferdinand Soethe



Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
> 
> Ross Gardler wrote:
> 
> RG> No need to install ant you already have it in the tools directory of
> RG> Forrest. Just put FORREST_HOME/tools/ant/bin on your PATH env variable.
> 
> Thanks.
> 
> I know that people should dig around in the Forrest dirstribution and
> find these things on their own, but for all the less inquisitive minds
> (like me) how about adding this as first step to the build ...
> instructions in howto-buildPlugin.xml?

Good idea.

Can I ask that you provide a patch for this rather than a new document. 
It makes it much easier to get it into SVN that way.

To create a patch see http://forrest.apache.org/contrib.html#patch

Thanks,
Ross




Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ferdinand Soethe <sa...@soethe.net>.

Ross Gardler wrote:

RG> No need to install ant you already have it in the tools directory of
RG> Forrest. Just put FORREST_HOME/tools/ant/bin on your PATH env variable.

Thanks.

I know that people should dig around in the Forrest dirstribution and
find these things on their own, but for all the less inquisitive minds
(like me) how about adding this as first step to the build ...
instructions in howto-buildPlugin.xml?

<section>
        <title>Make ant available on the command line</title>
        <p>
                The following instructions rely heavily on
                <a href="http://ant.apache.org/">ant</a>
                to automate some steps in the process. Since ant
                is distributed as part of Forrest, all you need to do
                is add the ant executable directory to your system path. They
                are located in the
                <code>tools\ant\bin</code>
                subdirectory of your Forrest directory.
        </p>
        <p>
                Alternatively you can prefix all calls to ant in
                the following instructions with the full path to the ant binary directory.
        </p>
    </section>


Below I include the full updated howto as text.
--
Ferdinand Soethe




<?xml version="1.0" encoding="UTF-8"?>
<!--
  Copyright 2002-2004 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 howto PUBLIC "-//APACHE//DTD How-to V2.0//EN" "http://forrest.apache.org/dtd/howto-v20.dtd">
<howto>
  <header>
    <title>How to Build a Plugin</title>

    <version>0.1</version>

    <abstract>This How-To describes the steps necessary to build a plugin for 
    Forrest. Forrest uses plugins to add new input formats, output formats
    and to change its default behaviour. Since plugins are downloaded when
    needed and can be hosted at any location plugin code can be developed 
    independantly of Apache Forrest. This how-to describes each of the major
    steps in creating a plugin and then works through some examples of 
    plugin creation in order to illustrate the materials.</abstract>

    <last-modified-content-date date="2005-03-03" />
  </header>

  <audience title="Intended Audience">
    <p>Users needing to add additional input formats or output formats or
    to change the way Forrest internals work.</p>
    
    <warning>The Plugin Infrastructure is still at an early stage of design 
    and implementation, consequently this How-To <em>may</em> be out of date
    and/or incomplete. If you are having problems with any of the steps 
    described, please ask for help on the developers mailing list (and then
    provide patches for this document).</warning>
    <warning>Please make sure that you are using forrest 0.7-dev if you want use 
    plugins. Forrest 0.6 will not work!!!</warning>
  </audience>

  <purpose title="Purpose">
    <p>This How-To will illustrate how to build a plugin, publish a plugin
    and configure a Forrest project to use their plugin.</p>
  </purpose>

  <prerequisites title="Prerequisites">
    <p>Plugin developers should have:</p>
    
    <ul>
      <li>a basic knowledge of XML, XSLT and Cocoon pipelines</li>
      <li>a clear use-case for extending Forrest</li>
      <li>verified with the Apache Forrest developer community that the
      requried functionality does not already exist</li>
    </ul>
  </prerequisites>

  <steps title="Steps">
    <p>Here is how to proceed.</p>

    <section id="typeOfPlugin">
      <title>Type of Plugin</title>

      <p>There are three types of plugin, each with a clear purpose, you
      must first decide which 
      <a href="site:documentation/developers/pluginInfrastructure">type of plugin</a>
      you need to build.</p>
      
    </section>
    
    <section>
        <title>Make ant available on the command line</title>
        <p>
                The following instructions rely heavily on
                <a href="http://ant.apache.org/">ant</a>
                to automate some steps in the process. Since ant
                is distributed as part of Forrest, all you need to do
                is add the ant executable directory to your system path. They
                are located in the
                <code>tools\ant\bin</code>
                subdirectory of your Forrest directory.
        </p>
        <p>
                Alternatively you can prefix all calls to ant in
                the following instructions with the full path to the ant binary directory.
        </p>
    </section>
    
    <section>
      <title>Seed a New Plugin</title>
      <p>Regardless of the type of plugin you are building, the directory
      structure is almost identical, as are most of the requried
      configuration files. In this How-To we will assume that you are creating a 
      plugin in the Forrest source tree. All plugins are developed in the
      <code>forrest/plugins</code> directory.</p>
      
      <p class="instruction">Run the following set of commands:</p>
      
      <source>
      cd [path_to_forrest]/plugins
      ant seedPlugin
      </source>      
      
      <p>The above ant target will ask you the name of the plugin and will
      build a minimal plugin directory structure and configuration. You will 
      need to customise these files to build your plugin.</p>
      
      <note>Although you can name your project anything you like we do have 
      some <a href="site:documentation/developers/pluginInfrastructure">naming 
      coventions</a> that we recomend you follow.</note> 
      
      <note>If you plan on building your plugin elsewhere you can copy the
      <code>build.xml</code> build file to your own plugin work directory and 
      use it there.</note>
      
      <p>See 
      <a href="site:documentation/developers/pluginInfrastructure">What Does 
      a Forrest Plugin Look Like?</a> for more information on the plugin
      directory structure and configuration files.</p>
    
      <section>
        <title>Edit the Plugin Template</title>
        <p>You now have a skeleton plugin project. However, it doesn't do 
        anything useful yet. Now is a good time to edit some of the files
        provided. For example:</p>
        
        <section>
          <title>status.xml</title>
          <p>This file is used to track changes to the plugin
          project and to manage lists of things that still need to be done.
          At this stage you should correct the <code>person</code> entry
          near the top of the file. It is also a good idea to add a few key
          milestones in the task list towards the bottom of the file.</p>
          
          <p>As you work on the plugin you should record all major changes in
          this file so that it can then be used as a changelog for your
          plugin.</p>
        </section>
        
        <section>
          <title>forrest.properties</title>
          
          <p>This file defines many configuration parameters for Forrest. It
          does not need to be customised in most cases. However, see
          for more details.</p>
        </section>
        
        <section>
          <title>src/documentation/skinconf.xml</title>
          <p>This configures the skin for your plugins documentation. There
          are some items that need to be configured in here, for example, the
          copyright information. The file is heavily commented so probably
          best to read through it, changing what you need to.</p>
        </section>
        
        <section>
          <title>Documentation</title>
          <p>It is also a good idea to start writing the documentation at this
          stage. The above process created a very simple plugin documentation
          site for you. All you have to do is add the content.</p>
        </section>
      </section>
    </section>
    
    <section>
      <title>Edit the Plugin XMap file(s)</title>
      <p>The plugin <code>xmap</code> file is a Cocoon sitemap that is mounted
      at a strategic place in the Forrest pipeline. It is in this file
      that you will instruct Forrest how to operate. An input plugin
      must provide a <code>input.xmap</code> file, an output plugin
      must provide a <code>output.xmap</code> file, whilst an internal
      plugin provides a <code>internal.xmap</code> file. In addition, an
      input plugin may provide a <code>resources.xmap</code> file to
      allow the plugin to handle items such as JavaScript files.</p>
      
      <p>It is beyond the scope of this How-To to give details about how to 
      build your plugins XMap. See the 
      <a href="site:documentation/developers/sitemap-ref">Sitemap Reference</a> for general
      information. See also 
      <a href="site:documentation/developers/pluginInfrastructure">Plugin Infrastructure</a>
      for some hints and tips on creating plugin sitemaps. In addition, as with
      all development work on Forrest, you will find
      the <a href="ext:forrest/mail-lists/forrest-dev">developer mailing list</a>
      a very doog resource (check the archives before posting, please).</p>
      
      <section>
        <title>Components, Actions and Resources</title>
        <p>If your plugin uses any components (i.e. generators, transformers or
        serializers), actions or resources they must
        be defined in either the plugins xmap or one of its parents. The parents
        of an <code>input.xmap</code> are <code>sitemap.xmap</code> and
        <code>forrest.xmap</code>, whilst the parent of both 
        <code>output.xmap</code> and <code>internal.xmap</code> are 
        <code>sitemap.xmap</code>.</p>
        <p>If you want to use the realpath where the sitemap.xmap of your plugin 
        resides then you have to use 
        <code>{forrest:plugins}/PLUGIN_NAME</code> instead of <code>{realpath:/}</code>.
        </p>
        <p>See the examples below for more details.</p>
      </section>
    </section>
    
    <section>
      <title>Create the Necessary Resource Files</title>
      <fixme author="rdg">Discuss the XSL files and other such resources</fixme>
    </section>
    
    <section>
      <title>Create Samples in the Documentation</title>
      <p>Plugin documentation should provide (as a minimum) an
      index page that provides an overview and a set of samples that demonstrate
      the functionlaity of the plugin. Typically these samples will be
      provided in a <code>samples</code> subdirectory in the plugin 
      documentation and will be referenced from both <code>site.xml</code>
      and <code>tabs.xml</code>.</p>
      
      <p>Try to provide a sample for all the major functions of your plugin
      and document any configuration that is available.</p>
    </section>
    
    <section>
      <title>Testing a Plugin</title>
      <p>Since your documentation for the plugin illustrates all of its 
      functionality you can use that site for testing the plugin. However, you
      must first deploy in your local install of Forrest. Each plugin contains
      a buildfile that includes a <code>test</code> target. This target, by
      default, builds the documtantion for your plugin.</p>
      
      <p class="instruction">Run the command <code>ant test</code> in
      the plugins directory.</p>
      
      <p>Of course, the build should complete without errors.</p>
      
      <note>You can also use <code>forrest run</code> to interactively examine
      your documentation (point your prowser at 
      <a href="http://localhost:8888">http://localhost:8888</a>).</note>
      
      <p>It is also a really good idea to build proper tests for your 
      plugins using a suitable testing framework, for example, 
      <a href="http://webtest.canoo.com/">WebTest</a>. We recomend that you
      extend the <code>test</code> target in your plugins build file because
      this target is also used when performing integration tests on Forrest.
      In addition, we recomend that you use the samples in your documentation 
      for your tests, this way you are documenting your plugin at the same time 
      as writing your tests.</p>
    </section>
    
    <section>
      <title>Releasing a Plugin</title>
    
      <section>
        <title>Register the Plugin with Apache Forrest</title>
        <fixme author="rdg">Describe the plugins.xml file</fixme>
        <fixme author="rdg">Describe making a request of Forrest devs for 
        inclusion</fixme>
      </section>
      
      <section>
        <title>Deploying the Plugin</title>
        <p>To deploy the plugin so that others can use it, it must be made 
        available as a zip from the URL indicated in the 
        <code>plugins.xml</code> file. The plugins build file provides targets 
        to assist with this task.</p>
        
        <p class="instruction">To deploy a plugin simply run the command
        <code>ant deploy</code> from within the plugin directory.</p>
        
        <p>This command will, by default, deploy to the Apache Forrest web site.
        In order to do this you need write access to Forrest. If you want to
        deploy your plugin to a different location you 
        can build the zip of your plugin with <code>ant dist</code>
        and then copy the zip file from <code>build/dist</code> to wherever
        you intend to host the plugin.</p>
        
        <note>Running this command on any plugin will also deploy any
        changes to the <code>plugins.xml</code> file. If you are deploying to
        your own website you will have to request changes to the 
        <code>plugins.xml</code> and have a Forrest committer publish the new
        document.</note>
        
        <warning>Running the <code>deploy</code> or <code>dist</code> targets
        will always run the <code>test</code> target first. This is to ensure
        that your only deploy working plugins. This adds a little time to
        the deploy cycle, but we feel the peace of mind is worth it.</warning>
        
      </section>
    </section>
    
    <section>
      <title>Examples</title>
      <p>This section will provide some example plugins to help illustrate the
      steps discussed above.</p>
        <section>
          <title>Input Plugin</title>
          <fixme author="RDG">Discuss OpenOffice.org plugin here</fixme>
        </section>
        
        <section>
          <title>Output Plugin</title>
          <fixme author="RDG">Discuss s5 plugin here</fixme>
        </section>
        
        <section>
          <title>Internal Plugin</title>
          <fixme author="RDG">Discuss IMSManifest plugin here</fixme>
        </section>
    </section>

    <section id="extension">
      <title>Further Reading</title>
      
      <ul>
        <li><a href="site:documentation/developers/pluginInfrastructure">Plugin Infrastrucuture Documentation</a> for Developers</li>
        <li><a href="site:documentation/plugins">Plugins Documentation</a> for users</li>
      </ul>
    </section>

    <section id="summarise">
      <title>Summarise the Entire Process</title>

      <fixme author="rdg">In a few sentences, remind the reader what they have just learned.
      This helps to reinforce the main points of your How-To.</fixme>
    </section>
  </steps>
</howto>




Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
> Thanks both of you for that quick advice.
> 
> But I think I'm missing something here. In the docs it says
> 
> JS> When Forrest installs a plugin it downloads a zip of the plugin
> JS> code and extracts it into the plugins directory of Forrest and an
> JS> entry is made in src/plugins/sitemap.xmap. For example, installing
> JS> the IMSManifest plugin described above will result in the
> JS> following entry being added to the plugin sitemap:
> 
> So why is a change to a stylesheet in
> 
> [forrest programm dir]\plugins\org.apache.forrest.plugin.OpenOffice.org\resources\stylesheets\openoffice-common2forrest.xsl
> 
> not visible right away. Is there a caching step that's not mentioned
> here?

This is because if you install the forthcoming binary version of 0.7, 
you won't get the plugins, only the core, plugins are downloaded as and 
when they are needed.

The ant local-deploy is the equivalent of downloading over the network, 
but it does it with your local changes.

There is an issue in the tracker to make the system work with the 
plugins inplace when they are available, this will remove the need for 
ant local-deploy.

> JS> I think that then it's not even necessary to restart
> JS> forrest.
> 
> So in other words if I restart (forrest run) or redo my static forrest
> it should work? (does not right now!)

See above.


> JS> You'll need to do a "local-deploy" in the plugin's
> JS> directory for the changes to happen:
> 
> JS>    My-Plugin$>ant local-deploy
> 
> Will install ant ant try this ant see if it makes an(t)y difference :-)

No need to install ant you already have it in the tools directory of 
Forrest. Just put FORREST_HOME/tools/ant/bin on your PATH env variable.

Ross

Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ferdinand Soethe <sa...@soethe.net>.
Thanks both of you for that quick advice.

But I think I'm missing something here. In the docs it says

JS> When Forrest installs a plugin it downloads a zip of the plugin
JS> code and extracts it into the plugins directory of Forrest and an
JS> entry is made in src/plugins/sitemap.xmap. For example, installing
JS> the IMSManifest plugin described above will result in the
JS> following entry being added to the plugin sitemap:

So why is a change to a stylesheet in

[forrest programm dir]\plugins\org.apache.forrest.plugin.OpenOffice.org\resources\stylesheets\openoffice-common2forrest.xsl

not visible right away. Is there a caching step that's not mentioned
here?

JS> I think that then it's not even necessary to restart
JS> forrest.

So in other words if I restart (forrest run) or redo my static forrest
it should work? (does not right now!)

JS> You'll need to do a "local-deploy" in the plugin's
JS> directory for the changes to happen:

JS>    My-Plugin$>ant local-deploy

Will install ant ant try this ant see if it makes an(t)y difference :-)


Ferdinand



Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Ross Gardler <rg...@apache.org>.
Johannes Schaefer wrote:
> You'll need to do a "local-deploy" in the plugin's
> directory for the changes to happen:
> 
>   My-Plugin$>ant local-deploy
> 
> See plugins/build.xml

Or you can do ant test which will local-deploy the plugin files and run 
the tests (i.e. build the plugin documentation)

For more info see 
http://forrest.apache.org/docs/dev/howto/howto-buildPlugin.html

(I now realise that this document does not have a description of ant 
local-deploy in it).

> I think that then it's not even necessary to restart
> forrest.

That is right.

Ross

Re: Questions on extending the OOwriter-PlugIn to support HowTos

Posted by Johannes Schaefer <jo...@uidesign.de>.
You'll need to do a "local-deploy" in the plugin's
directory for the changes to happen:

   My-Plugin$>ant local-deploy

See plugins/build.xml

I think that then it's not even necessary to restart
forrest.

Cheers
Johannes



Ferdinand Soethe wrote:
> Hi Ross,
> 
> I'm trying to extend your OOWriter-Plugin to support HowTos and
> so far it looks quite easy to do.
> 
> 1. Changed OpenOffice-common2Forrest to insert some HowTo Header Info
>    by adding the quoted sections:
> 
>   <!--+
>       | start transforming 
>       +-->
>   <xsl:template match="/">
>     <document>
>       <header>
>         <title>
>           <xsl:choose>
>             <xsl:when test="/office:document/office:meta/dc:title = '' or not(/office:document/office:meta/dc:title)">
>               <xsl:value-of select="$filename"/>
>             </xsl:when>
>             <xsl:otherwise>
>               <xsl:value-of select="/office:document/office:meta/dc:title"/>
>             </xsl:otherwise>
>           </xsl:choose>
>         </title>
> 
>>        <!-- Abstract is required field in HowTos, so always create it and fill with description field  -->
>>        <xsl:choose>
>>                <abstract>
>>                        <xsl:when test="/office:document/office:meta/dc:description = '' or not(/office:document/office:meta/dc:description)">
>>                        </xsl:when>     
>>                        <xsl:otherwise>
>>                        <xsl:value-of select="/office:document/office:meta/dc:description"/>
>>                </xsl:otherwise>
>>                </abstract>
>>        </xsl:choose> 
>>        
>>        <!-- last modified date -->
>>        <last-modified-content-date date="format-dateTime({/office:document/office:meta/dc:date}, '[Y]-[M]-[D]')"/>
> 
> 
> 
>         <xsl:call-template name="style"/>
>       </header>
>       <xsl:apply-templates select="//office:body"/>
>     </document>
>   </xsl:template>
>   
>   <!--+
>       | create the body 
>       +-->
>   <xsl:template match="office:body">
>     <body>
> 
>        <!-- This is special for HowTo-Documents. Will make this
>             conditonal as soon as it is working  -->
> 
>>     <header>
>>        <title>
>>          <xsl:choose>
>>            <xsl:when test="/office:document/office:meta/dc:title = '' or not(/office:document/office:meta/dc:title)">
>>              <xsl:value-of select="$filename"/>
>>            </xsl:when>
>>            <xsl:otherwise>
>>              <xsl:value-of select="/office:document/office:meta/dc:title"/>
>>            </xsl:otherwise>
>>          </xsl:choose>
>>        </title>
>>
>>        <!-- Abstract is required field in HowTos, so always create it and fill with description field  -->
>>        <xsl:choose>
>>                <section id="Overview">
>>                        <title>Overview</title>
>>                        <p>
>>                        <xsl:when test="/office:document/office:meta/dc:description = '' or not(/office:document/office:meta/dc:description)">
>>                        </xsl:when>
>>                        <xsl:otherwise>
>>                        <xsl:value-of select="/office:document/office:meta/dc:description"/>
>>                </xsl:otherwise>
>>                        </p>
>>                </section>
>>        </xsl:choose>
>>      </header>
> 
> 
>     
>       <xsl:apply-templates select="key('rootChildren', generate-id())"/>
>       <xsl:apply-templates select="text:h[@text:level='1']"/>      
>     </body>
>   </xsl:template>
> 
> 
> 2. I used and tested the OO-Plugin before modifying the file in the
>    plug-ins-dir then changed above file and re-ran Forrest
> 
>    Funny thing is, nothing changes. It still compiles w/o errors, but
>    none of the elements show. Tried and called the document.xml and
>    it's not there either.
> 
>  Do I need to somehow reload plugins after I've changed
>  stylesheets or where is my mistake here?
> 
> 
> --
> Ferdinand Soethe
> 
> 
> 


-- 
User Interface Design GmbH * Teinacher Str. 38 * D-71634 
Ludwigsburg
Fon +49 (0)7141 377 000 * Fax  +49 (0)7141 377 00-99
Geschäftsstelle: User Interface Design GmbH * 
Lehrer-Götz-Weg 11 * D-81825 München
www.uidesign.de

Buch "User Interface Tuning" von Joachim Machate & Michael 
Burmester
www.user-interface-tuning.de

Besuchen Sie uns auf der Hannover Messe 11.-15. April 2005
Halle 2, Stand C14 auf dem MMI Gemeinschaftsstand
www.uidesign.de/hmi2005

Nächstes TAE-Seminar zu User Interface Design
Ostfildern-Nellingen, 07.-08. April 2005
www.tae.de TAE-Veranstaltung Nr. 31189