You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Paul Bolger <pb...@gmail.com> on 2006/03/07 05:46:49 UTC
Modifying plugin
I've been building a site with the Dispatcher, using the Open Office
plugin to translate documents to Forrest internal document format. I
found that I had to make a couple of minor modifications to the plugin
- turned off the warning that the heading hierarchy is wrong (the
documents are supplied by others and I'm doing this to save myself
time - I can try and convince the clients that the documents will look
better if they structure them correctly, but I'm not going to fix
their mistakes for them.) I also turned off the class which puts an
arrow graphic at the start of each line, for some reason the plugin
thinks every line deserves an arrow...
Anyhow, to prevent my modifications from being overwritten by
Subversion I copied the plugin, renamed the copy, searched the new
directories for any mention of the old plugin name, and then changed
forrest.properties to the new plugin name. Works fine.
My question is: is there a less clunky way of modifying a plugin, or
is what I did the best way?
Re: Modifying plugin
Posted by Ross Gardler <rg...@apache.org>.
Paul Bolger wrote:
>>It would be great if you could provide a patch or this. The advantage is
>>that you will not have to keep your OOo plugin in synch with the one we
>>release and, of course, we all get the benefit of your work.
>
>
>
> I've made a patch, but can't see the option appearing in
> forrest.properties in a new seed. Wondering whether I've been
> modifying the wrong instance of the plugin. Should it be the one i the
> plugins dir?
I'm not following your question here. I never said anything about
forrest.properties, I described a new property system that uses XML
files for properties (forrest.properties.xml and
default.plugin.properties.xml). Can you describe exactly what you mean?
With respect to which plugin to modify. The best process is:
- edit the src in the plugins dir
- do ant local-deploy
In this case you need to restart forrest as the new properties system
does not currently support dynamic reloading.
(ASIDE: We have issues to remove the need to do the local-deploy and to
dynamically reload properties, but they are not implemented yet.)
> I also notice, on a slightly different subject, that data loss can
> occur with the OOo plugin: If your source doc contains headings deeper
> than h5 they are skipped in the output.
>
> Obviously this is not nice... My XSLT isn't good enough to fix this,
> but a good thing to do at the moment might to put a warning in the
> docs.
And to raise an issue to remind us to fix it. Can you send us a patch
for the docs and apply it to said issue?
> Next question: Where are the docs for this plugin?
All plugin docs are in the plugins src directory, e.g.
FORREST_HOME/plugins/org.apache.forrest.plugin.input.OpenOffice.org
They are just a normal Forrest project.
> The link from 0.8 dev is broken
>
> http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.OpenOffice.org
>
> So's the one from 0.7
Yes, see the recent thread on this issue, its a problem of versioned
plugins. We *must* fix this...
> I don't mind fixing them, but need to know where the previous ones (if
> they exist) are.
They are generated from the plugins.xml file, so it is not a simple case
of editing a doc. See http://issues.apache.org/jira/browse/FOR-533 for a
n issue for tracking this (and related issues).
> I've found
>
> plugins\org.apache.forrest.plugin.input.OpenOffice.org\src\documentation\content\xdocs\samples\openoffice-writer-howto.sxw
>
> But it's really not very informative about the working of the plugin.
That's about it I'm afraid. The code is our only other documentation ;-)
See the input.xmap file which will show you how it works (and ask
questions of course - I'll be online on and off during Forrest Friday if
you want to have a chat to understand things).
Ross
Re: Modifying plugin
Posted by Paul Bolger <pb...@gmail.com>.
> It would be great if you could provide a patch or this. The advantage is
> that you will not have to keep your OOo plugin in synch with the one we
> release and, of course, we all get the benefit of your work.
I've made a patch, but can't see the option appearing in
forrest.properties in a new seed. Wondering whether I've been
modifying the wrong instance of the plugin. Should it be the one i the
plugins dir?
I also notice, on a slightly different subject, that data loss can
occur with the OOo plugin: If your source doc contains headings deeper
than h5 they are skipped in the output.
Obviously this is not nice... My XSLT isn't good enough to fix this,
but a good thing to do at the moment might to put a warning in the
docs.
Next question: Where are the docs for this plugin?
The link from 0.8 dev is broken
http://forrest.apache.org/pluginDocs/plugins_0_80/org.apache.forrest.plugin.input.OpenOffice.org
So's the one from 0.7
I don't mind fixing them, but need to know where the previous ones (if
they exist) are.
I've found
plugins\org.apache.forrest.plugin.input.OpenOffice.org\src\documentation\content\xdocs\samples\openoffice-writer-howto.sxw
But it's really not very informative about the working of the plugin.
Re: Modifying plugin
Posted by Paul Bolger <pb...@gmail.com>.
> Now, back to parameterisation.
>
> In 0.7 it is not easy to parameterise plugins. It is possible, but
> complex and requires modifications to core, which is obviously not a
> good thing for a plugin to do. In 0.8-dev though it is much easier.
>
> Basically, you create a default.plugin.properties.xml file in the root
> of the plugin directory and add any properties you need. In this case we
> want a property to define if we are to allow incorrect heading
> hierarchies. SO our default.properties.xml plugin would look like
> something like this:
>
> <?xml version="1.0" encoding="UTF-8"?>
> <properties>
> <!-- OpenOffice plugin properties -->
>
> <!-- OpenOffice documents can be created with poorly structured
> heading hierarchies. This is bad practice and can result in unintended
> visual effects when rendering in other formats. Set this property to
> true if you would like the plugin to insert a warning in such documents. -->
>
> <property name="OOo.headingsHierarchy.warning" value="true"/>
>
> </properties>
>
> Now we need to pass this parameter into the stylesheets so that they can
> be modified to behave as required. This requires a modification to the
> input.xmap, for example:
>
> add
> <map:parameter name="warnHeadingHierarchies"
> value="{project:OOo.headingHierarchy.warning}" />
>
> to the sx* transformations, i.e.:
>
> <map:when test="{lm:project.{uri}.sxw}">
> <map:match type="regexp" pattern="^(.*?)([^/]*).xml$">
> <!-- FIXME: use the OOo generator as seen in the resume
> plugin -->
> <map:generate src="{lm:OOo.bootstrap}"/>
> <map:transform
> src="{lm:OOo.transform.xsl.aggregates/openoffice-document}">
> <map:parameter name="src" value="{lm:project.{1}{2}.sxw}"/>
> </map:transform>
> <map:transform type="cinclude"/>
> <map:transform
> src="{lm:OOo.transform.openoffice-writer.forrest}">
> <map:parameter name="filename" value="{2}" />
> <map:parameter name="extension" value="sxw" />
> <map:parameter name="warnHeadingHierarchies"
> value="{project:OOo.headingHierarchy.warning}" />
> </map:transform>
> <map:serialize type="xml-document"/>
> </map:match>
> </map:when>
>
> Finally we need to make the XSL behave differently according to this
> parameter:
>
> <xsl:param name="warnHeadingHierarchies"/>
>
> ...
>
> <xsl:if test="warnHeadingHierarchies='true'">
> <!-- add the warning -->
> </xsl:if>
>
> Now, if the user wants to change this behaviour all they need to do is
> override the value of OOo.headingsHierarchy.warning in
> forrest.properties.xml in their project root.
>
> It is also possible for individual users to change the value of this
> using local.forrest.properties.xml.
>
> ---
>
> It would be great if you could provide a patch or this. The advantage is
> that you will not have to keep your OOo plugin in synch with the one we
> release and, of course, we all get the benefit of your work.
alright, I'm currently digesting this....
Re: Modifying plugin
Posted by Ross Gardler <rg...@apache.org>.
Paul Bolger wrote:
>>"Information loss" is not very accurate, I should have said something
>>like "unpredictable behaviour". Here's just one example of such
>>unpredictable behaviour:
...
> I can live with that. The problem here is with the people writing the
> docs. I might have to see if I can work out some way of forcing them
> to use a logical structure. Beyond switching to a CMS I'm not sure
> what the answer is, if people insist on making new styles every time
> they want text to look different, and use asterisks to make lists,
> it's always going to be a nightmare converting their documents.
Yes the problems of "WYSIWYG" editors are that they produce poorly
structured and inconsitent content. OOo is a massive improvement over
other editos, but it still suffers.
I always intended to create a version of OOo that only had the styles
availablt tat I wanted to suppor, never got around to it so far. That
would solve many of the problems. It would leave a few too, such as
using '*' for bullets, but at least that will render reasonably wll in
the majority of output formats (it would fall apart in some renderings
though, such as voice).
>>><!--+
>>> | Instructional step
>>> +-->
>>> <xsl:template match="text:p[@text:style-name='P2']">
>>> <p class="instruction">
>>> <xsl:apply-templates/>
>>> </p>
>>> </xsl:template>
>>></xsl:stylesheet>
...
>>P2 is defined in the SXW How-To template as an instruction. This is
>>clumsy, it should be a named style not an OOo defiend style (which is
>>P2). We need to change the How-To template document
>
>
> sorry, you've lost me here - the How-To template?
Open the sxw samples (wither the writer or the how-to) and you will see
that they define specific styles, such as "Forrest: Instructional Step",
which is the one that causes the arrow. These documents can be used as
templates for new documents. I'm not sure why they have never ben saved
as ODT files, I seem to remember a discussion abut a bug somewhere.
Ross
Re: Modifying plugin
Posted by Paul Bolger <pb...@gmail.com>.
> "Information loss" is not very accurate, I should have said something
> like "unpredictable behaviour". Here's just one example of such
> unpredictable behaviour:
>
> Consider a TOC built within OOo. It includes all headings of level 1 or
> 2. If you go from level 1 heading to level 3 heading this will be OK,
> but in Forrest how is this handled? Does it convert
>
> Heading 1
> blah blah
> Heading 3
> blah blah
>
> to
>
> <section>
> <title>Heading 1</title>
> <p>blah blah</p>
> <section>
> <title>Heading 3</title>
> <p>blah blah</p>
> </section>
> </section>
>
> or to
>
> <section>
> <title>Heading 1</title>
> <p>blah blah</p>
> <section>
> <section>
> <title>Heading 3</title>
> <p>blah blah</p>
> </section>
> </section>
> </section>
I can live with that. The problem here is with the people writing the
docs. I might have to see if I can work out some way of forcing them
to use a logical structure. Beyond switching to a CMS I'm not sure
what the answer is, if people insist on making new styles every time
they want text to look different, and use asterisks to make lists,
it's always going to be a nightmare converting their documents. Might
be a nice add-on for the OO plugin though: a 'heading collapser':
parse the doc after translation and collapse all headings into
sequence. Could have unpredicable effects though. It has occured to me
that what is really required here is a program which can look at a MS
Word doc and go "this is how you intended to format this" from the
visual layout. If anyone's aware of anything like this I'd be
interested :)
> >>Your point about an "arrow graphic" confuses me. I have never seen this,
> >>so it is a specific use in your case. Certainly, the samples, such as
> >>[1], do not exhibit this behaviour. It would be best for us to figure
> >>out why this is happening and improve the stylesheets to prevent it
> >>happening when not expected, as in your case. Can you post the code
> >>snippet you needed to change for this.
> >
> >
> > the relevant line out of the stylesheet (pelt.screen.css) is
> >
> > p.instruction {
> > display: list-item;
> > list-style-image: url('../themes/images/instruction_arrow.png');
> > list-style-position: outside;
> > margin-left: 2em;
> > }
>
> OK so the graphic is inserted by the stylesheet, not the OOo. But why is
> your text being marked as an instruction...
>
> > in
> >
> > openoffice-writer-to-forrest.xsl
> >
> > the code was
> >
> > <!--+
> > | Instructional step
> > +-->
> > <xsl:template match="text:p[@text:style-name='P2']">
> > <p class="instruction">
> > <xsl:apply-templates/>
> > </p>
> > </xsl:template>
> > </xsl:stylesheet>
>
> Ahhh...
>
> P2 is defined in the SXW How-To template as an instruction. This is
> clumsy, it should be a named style not an OOo defiend style (which is
> P2). We need to change the How-To template document
sorry, you've lost me here - the How-To template?
to provide a named
> style for this and leave the OOo defined style names unnafected by the
> OOo stylesheet since we have no control over how they are defined.
>
> > beats me why it's being triggered by this specific document. The doc
> > in question originated in MS Word and was translated to sxw by OO 2.0,
> > and the problem happened across a few docs I was referencing.
>
> Just coincindence that some internal MS style has been converted to "P2"
> in the OOo docs. The above should fix this.
Yes, see above. As stated I'm not that worried about the output being
that slick, I just need this to work easily, and the html is about
%1000 better than I'd get if I used MS html generation. I figure I can
attempt to educate the authors (with some tips on the section index
pages) and hope they get the message.
Re: Modifying plugin
Posted by Ross Gardler <rg...@apache.org>.
Paul Bolger wrote:
>>Firstly, the warning about heading hierarchy. This warning is there for
>>a reason, in some cases information may be lost if the hierarchy is not
>>correct. You need to be very careful if turning it off. However, your
>>point is valid and this should really be parameterised, more on this below.
>
>
> Point taken. I'd be interested to know when this would cause
> information loss: obviously no one wants that...
"Information loss" is not very accurate, I should have said something
like "unpredictable behaviour". Here's just one example of such
unpredictable behaviour:
Consider a TOC built within OOo. It includes all headings of level 1 or
2. If you go from level 1 heading to level 3 heading this will be OK,
but in Forrest how is this handled? Does it convert
Heading 1
blah blah
Heading 3
blah blah
to
<section>
<title>Heading 1</title>
<p>blah blah</p>
<section>
<title>Heading 3</title>
<p>blah blah</p>
</section>
</section>
or to
<section>
<title>Heading 1</title>
<p>blah blah</p>
<section>
<section>
<title>Heading 3</title>
<p>blah blah</p>
</section>
</section>
</section>
The former will result in heading 3 being in the TOC (which is
unintended), the latter will result in yet more unpredictable behaviour
since some output formats are incapable of representing sections with no
title (such as HTML and XHTML1, but not XHTML2)
>>Your point about an "arrow graphic" confuses me. I have never seen this,
>>so it is a specific use in your case. Certainly, the samples, such as
>>[1], do not exhibit this behaviour. It would be best for us to figure
>>out why this is happening and improve the stylesheets to prevent it
>>happening when not expected, as in your case. Can you post the code
>>snippet you needed to change for this.
>
>
> the relevant line out of the stylesheet (pelt.screen.css) is
>
> p.instruction {
> display: list-item;
> list-style-image: url('../themes/images/instruction_arrow.png');
> list-style-position: outside;
> margin-left: 2em;
> }
OK so the graphic is inserted by the stylesheet, not the OOo. But why is
your text being marked as an instruction...
> in
>
> openoffice-writer-to-forrest.xsl
>
> the code was
>
> <!--+
> | Instructional step
> +-->
> <xsl:template match="text:p[@text:style-name='P2']">
> <p class="instruction">
> <xsl:apply-templates/>
> </p>
> </xsl:template>
> </xsl:stylesheet>
Ahhh...
P2 is defined in the SXW How-To template as an instruction. This is
clumsy, it should be a named style not an OOo defiend style (which is
P2). We need to change the How-To template document to provide a named
style for this and leave the OOo defined style names unnafected by the
OOo stylesheet since we have no control over how they are defined.
> beats me why it's being triggered by this specific document. The doc
> in question originated in MS Word and was translated to sxw by OO 2.0,
> and the problem happened across a few docs I was referencing.
Just coincindence that some internal MS style has been converted to "P2"
in the OOo docs. The above should fix this.
Ross
That's a problem with the
Re: Modifying plugin
Posted by Paul Bolger <pb...@gmail.com>.
> You have two options right now, create a new plugin as you have done or
> parameterise the existing plugin behaviour. The best way to do it would
> be to parameterise the things you think need to change and commit the
> changes back to Forrest. My reasoning is that since you need it to work
> one way, and someone else needs it to work another way we need this to
> be an option.
Yep: easy to hack it till it works, but it doesn't add to the
usefulness of the app.
> However, looking at your comments some of your changes may be better
> made in the core without parameterisation, and you are doing the right
> thing by asking about them here.
>
> Firstly, the warning about heading hierarchy. This warning is there for
> a reason, in some cases information may be lost if the hierarchy is not
> correct. You need to be very careful if turning it off. However, your
> point is valid and this should really be parameterised, more on this below.
Point taken. I'd be interested to know when this would cause
information loss: obviously no one wants that... For my purpose
though, my clients would find this warning disturbing :) - better to
have it switchable so I can use it for debugging, then turn it off for
public consumption.
> Your point about an "arrow graphic" confuses me. I have never seen this,
> so it is a specific use in your case. Certainly, the samples, such as
> [1], do not exhibit this behaviour. It would be best for us to figure
> out why this is happening and improve the stylesheets to prevent it
> happening when not expected, as in your case. Can you post the code
> snippet you needed to change for this.
the relevant line out of the stylesheet (pelt.screen.css) is
p.instruction {
display: list-item;
list-style-image: url('../themes/images/instruction_arrow.png');
list-style-position: outside;
margin-left: 2em;
}
in
openoffice-writer-to-forrest.xsl
the code was
<!--+
| Instructional step
+-->
<xsl:template match="text:p[@text:style-name='P2']">
<p class="instruction">
<xsl:apply-templates/>
</p>
</xsl:template>
</xsl:stylesheet>
- right at the end of the stylesheet
beats me why it's being triggered by this specific document. The doc
in question originated in MS Word and was translated to sxw by OO 2.0,
and the problem happened across a few docs I was referencing.
> Now, back to parameterisation.
OK, I'll give it a go.
Re: Modifying plugin
Posted by Ross Gardler <rg...@apache.org>.
Paul Bolger wrote:
> I've been building a site with the Dispatcher, using the Open Office
> plugin to translate documents to Forrest internal document format. I
> found that I had to make a couple of minor modifications to the plugin
> - turned off the warning that the heading hierarchy is wrong (the
> documents are supplied by others and I'm doing this to save myself
> time - I can try and convince the clients that the documents will look
> better if they structure them correctly, but I'm not going to fix
> their mistakes for them.) I also turned off the class which puts an
> arrow graphic at the start of each line, for some reason the plugin
> thinks every line deserves an arrow...
> Anyhow, to prevent my modifications from being overwritten by
> Subversion I copied the plugin, renamed the copy, searched the new
> directories for any mention of the old plugin name, and then changed
> forrest.properties to the new plugin name. Works fine.
> My question is: is there a less clunky way of modifying a plugin, or
> is what I did the best way?
You have two options right now, create a new plugin as you have done or
parameterise the existing plugin behaviour. The best way to do it would
be to parameterise the things you think need to change and commit the
changes back to Forrest. My reasoning is that since you need it to work
one way, and someone else needs it to work another way we need this to
be an option.
We are working on a kind of "plugin inheritance", but this is not
operational right now. We need to resolve a couple of issues with
resolving resources via the locationmap first.
However, looking at your comments some of your changes may be better
made in the core without parameterisation, and you are doing the right
thing by asking about them here.
Firstly, the warning about heading hierarchy. This warning is there for
a reason, in some cases information may be lost if the hierarchy is not
correct. You need to be very careful if turning it off. However, your
point is valid and this should really be parameterised, more on this below.
Your point about an "arrow graphic" confuses me. I have never seen this,
so it is a specific use in your case. Certainly, the samples, such as
[1], do not exhibit this behaviour. It would be best for us to figure
out why this is happening and improve the stylesheets to prevent it
happening when not expected, as in your case. Can you post the code
snippet you needed to change for this.
Now, back to parameterisation.
In 0.7 it is not easy to parameterise plugins. It is possible, but
complex and requires modifications to core, which is obviously not a
good thing for a plugin to do. In 0.8-dev though it is much easier.
Basically, you create a default.plugin.properties.xml file in the root
of the plugin directory and add any properties you need. In this case we
want a property to define if we are to allow incorrect heading
hierarchies. SO our default.properties.xml plugin would look like
something like this:
<?xml version="1.0" encoding="UTF-8"?>
<properties>
<!-- OpenOffice plugin properties -->
<!-- OpenOffice documents can be created with poorly structured
heading hierarchies. This is bad practice and can result in unintended
visual effects when rendering in other formats. Set this property to
true if you would like the plugin to insert a warning in such documents. -->
<property name="OOo.headingsHierarchy.warning" value="true"/>
</properties>
Now we need to pass this parameter into the stylesheets so that they can
be modified to behave as required. This requires a modification to the
input.xmap, for example:
add
<map:parameter name="warnHeadingHierarchies"
value="{project:OOo.headingHierarchy.warning}" />
to the sx* transformations, i.e.:
<map:when test="{lm:project.{uri}.sxw}">
<map:match type="regexp" pattern="^(.*?)([^/]*).xml$">
<!-- FIXME: use the OOo generator as seen in the resume
plugin -->
<map:generate src="{lm:OOo.bootstrap}"/>
<map:transform
src="{lm:OOo.transform.xsl.aggregates/openoffice-document}">
<map:parameter name="src" value="{lm:project.{1}{2}.sxw}"/>
</map:transform>
<map:transform type="cinclude"/>
<map:transform
src="{lm:OOo.transform.openoffice-writer.forrest}">
<map:parameter name="filename" value="{2}" />
<map:parameter name="extension" value="sxw" />
<map:parameter name="warnHeadingHierarchies"
value="{project:OOo.headingHierarchy.warning}" />
</map:transform>
<map:serialize type="xml-document"/>
</map:match>
</map:when>
Finally we need to make the XSL behave differently according to this
parameter:
<xsl:param name="warnHeadingHierarchies"/>
...
<xsl:if test="warnHeadingHierarchies='true'">
<!-- add the warning -->
</xsl:if>
Now, if the user wants to change this behaviour all they need to do is
override the value of OOo.headingsHierarchy.warning in
forrest.properties.xml in their project root.
It is also possible for individual users to change the value of this
using local.forrest.properties.xml.
---
It would be great if you could provide a patch or this. The advantage is
that you will not have to keep your OOo plugin in synch with the one we
release and, of course, we all get the benefit of your work.
Ross
[1]
http://forrest.apache.org/pluginDocs/plugins_0_70/org.apache.forrest.plugin.input.OpenOffice.org/samples/openoffice-writer.html