[Proposal] extension plugin : placeholders/conditional blocks/...

[Jef Verelst <ku...@yahoo.com>]

Hello to you all,

the development group in which I work is facing some documentation issues. After evaluating how we could tackle them with our current commercial tool, we came to the conclusion that we needed to look at alternatives. We have been using cocoon-based XML document generation in our solution for some years now, so Forrest was an obvious  candidate. And it turned out that it can fulfill most of our needs as good (and sometimes even better) than the tool we now use. The extensible nature also allows us to overcome the problems we have with the current tool. 

However, there are a few functional holes that will need to be filled before we can migrate. What we need the most is :
* conditional blocks : we should be able to tag parts of the documents and include them based on settings.
* placeholders : text values that we can assign based on settings so that they can receive different values when generated for another target/customer.
* JavaHelp output format : parts of the documentation need to be accessible from a JavaHelp module.

I have looked at the plugin extension points of Forrest and have some ideas on how to fix them. As a first step, I made a prototype to handle the conditional blocks and the placeholders. I made a somewhat detailed description that already uses these 2 features.

My question is the following : could you spare us some of your time to have a look at it and let us know what you think of it? Main question is whether you are interested in it... if you judge that the things we are looking for are very specific to our situation, we'll develop it as part of our specific build process. If you see some general use in it, we could develop it as a public plugin. Any advice is of course also welcome.

I've set up a small site to store the proposal : http://uk.geocities.com/kullervo16/forrest.html

Thanks in advance.

Jef Verelst. 




      __________________________________________________________
Sent from Yahoo! Mail.
A Smarter Email http://uk.docs.yahoo.com/nowyoucan.html

Re: [Proposal] extension plugin : placeholders/conditional blocks/...

[Ross Gardler <rg...@apache.org>]

Jef Verelst wrote:
> Hello to you all,

Welcome.

> I've set up a small site to store the proposal :
> http://uk.geocities.com/kullervo16/forrest.html

With respect to you placeholder extension. There are a few alternative 
approaches that are already implemented:

a) use jx:templates or xi:includes
b) use xml entities

The jx:template approach is probably overkill for this use case. The 
xi:includes approah is almost identical to your proposal but does not 
require a custom file extension. The XML entities approach is probably 
the most efficient, but you'd probably have to jump the a few hoops.

xi:include allows full XPath expressions so you can easily extract the 
value you want from the XML placeholders file or you can use some cocoon 
magic to generate the placeholder data on the fly. So, I'd use the 
xi:include method. Search the user archives for discussion on how to use 
xi:include.

I'd use the same approach for your conditional sections. That is use an 
xi:include and have the sitemap decide on whether to insert content or 
not. The method you propose for this makes sense.

With respect to you JasvaHelp proposal, that sounds really useful. The 
only comment I would make is that you should not use an attribute on the 
root element to indicate inclusion or exclusion. This would require a 
change of the DTD which is overkill. I recommend using either a separate 
manifest file to describe all files that should be included/excluded or 
use the existing <meta...> element in the XDoc specification.

Your proposal doc mentions slides. You might want to take a look at the 
OOo plugin. This is woefully out of date (uses OOo V1), but it had 
partial support for OOo slides as an input format. There are also a s5 
and slidy plugins on sourceforge (due to licence incompatabilities) see 
http://forrestplugins.svn.sourceforge.net/viewvc/forrestplugins/trunk/forrestPlugins/

Finally, (also on sourceforge site above) there is an MSOffice plugin 
that uses OOo running as a headless server and the OOo plugin to convert 
from MS Office formats to Forrest formats.

However, with all these plugins you should be aware that they were built 
for a specific use, where they were useful, but they have not been 
developed further for use in the wider world. In other words, they are 
likely to give you a head start, but they are unlikely to work as is.

Ross

Ross