forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <>
Subject Re: [RT] plugin infrastructure
Date Sat, 06 Nov 2004 10:09:47 GMT
Ross Gardler wrote:
> Nicola Ken Barozzi wrote:
>> I'm thinking of the DocBook plugin and plugins that output the DocBook
>> as Sean has shown... so there is a dependency
>>   DocBook_outputting_plugin-> Docbook_plugin -> Forrest
> Isn't this just a roundabout way of providing a different intermediate 
> format? Why do we have to go via the Docbook route? I am not aware of 
> any formats that do not provide XHTML stylesheets that do provide 
> Docbook ones.
> In my view, a source plugin *must* provide our intermediate format. If 
> we keep it simple like this then we don't have any plugin dependencies 
> as everything goes via Forrest core.


Thanks for bringing me down to earth :-)

> That isn't to say that we will always think this way, but right now I 
> can't think of a valid use case where this is necessary. As I said 
> above, I cannot think of a single format that provides conversion to 
> Docbook but not to XHTML. Furthermore, we don't currently need the 
> complexity of the Docbook markup since we are only concerned with 
> publishing.

Ok, agreed.

The only other input format that we may need is DocBook, and for that 
case we can always hardcode a special match, without having to go to the 
plugin dependency route.

>> faq should start using the content aware pipelines, and this is solved.
> +1 this can be done when the faq stuff is moved to a plugin.
>> For other special *internal* parts we should probably not use name for
>> matching but maybe a parameter.
>>   *?forrest-part=site.xml
> +1, this could facilitate the generation of different Forrest parts for 
> different pages. There is no forrest-part at present that needs this, 
> but some time ago there was an RT about have Forrest provide additional 
> parts, for example, a news panel. These parts can be provided by 
> infrastructure plugins and using the above match we can customise on a 
> per page basis. For example, "index.html?forrest-part=news.xml" would 
> return news about project releases whilst 
> "developers/index.html?forrest-part=news.xml" would provide recent changes.

Hand on a second, let's go deeper in this.

I see three issues:

1 - the page is the context, the part is the data:
     forrest-part should show some extra data as it has to be shown
     on the page being rendered.

     forrest-part=tabs.xml would show the tabs with the selected one
     forrest-part=site.xml would show the site with the selected one

2 - the page is the data, and we specify a view
     for each page we may have different representations of it:
          -> MyClass.html  javadocs
          -> MyClass.html  UML graph
          -> MyClass.html  highlighted source code
          -> MyClass.html  checkstyle result

     How do we differentiate them? Not with parameters, as it has to
     remain in a name.

          -> MyClass-javadocs.html   javadocs
          -> MyClass-uml.html        UML graph
          -> MyClass-source.html     highlighted source code
          -> MyClass-checkstyle.html checkstyle result

      Problem: How do we define the "default" view, which is

3 - extra data to be put on a page

      Since we have to aggregate, we need to specify a new section
      for information nuggets. This is to make all skins able to render

      The question is: how to add things to the nugget section?
      Seems like the last point of this mail is getting more
      important :-)

>>> My Proposal
>>> ===========
>>> Each plugin should be able to provide three sitemaps rather than the 
>>> current 1.
>>> - sitemap.xmap - this provides the infrastructure matchers (i.e. 
>>> site.xml, faq.xml, issues.xml), as such it will be mounted before 
>>> *any* of the Forrest matches. This sitemap can override any behaviour 
>>> within Forrest)
>>> - source.xmap - this provides the source matchers (i.e. **.xml), it 
>>> is mounted in forrest.xmap before the default forrest **.xml 
>>> behaviour and therefore can override that default behaviour but it 
>>> will not interfere with any internal Forrest infrastructure matches, 
>>> or any other plugins infrastructure matches.
>>> - output.xmap - this provides (surprise!) the output matchers (i.e. 
>>> **.html, **.pdf, **.slides), it is mounted before any of the default 
>>> matchers for Forrest and so can override this default behaviour
>>> Ideally, each plugin should only provide one of these three sitemaps. 
>>> I believe this will help us to define a sensible granularity for the 
>>> plugins. However, further exploration of use cases may show otherwise 
>>> and therefore we should make it legal (but not encouraged) to 
>>> implement more than one of them.
>> I tend to like the concept, even if it may not result to be technically
>> needed. Just thinking out loud.
>>> Avoiding Plugin Conflicts
>>> -------------------------
>>> Clashes between plugins can occur. For example, the 
>>> simplified-docbook and full docbook plugins may try and process the 
>>> same files. In this instance the one that is mounted first will take 
>>> precedence. Plugins are mounted in the order they appear in the 
>>> project.required.plugins property, therefore the mounting order and 
>>> therefore processing precedence is under user control.
>> +1
>> Easy, simple, effective.
> <snip what="stuff we agree can wait"/>
>>> - Plugin resources are not 
>>> copied to site - in order to fix this problem I believe each plugin 
>>> should implement a site-build.xml file that provides a target for 
>>> copying any required resources into the built site. This is not 
>>> necessary when running dynamically.
>> Well, this is another RT altogether, about how to generate a site with 
>> non-linked resources.
> Actually, one of my plugins needs this now (the slideshow plugin) as 
> will the WYSIWYG editor I started last week (but have not had the time 
> to finish). I'm happy to implement the build file solution above. This 
> does not break the copyless behaviour since the plugin deals with the 
> matching, it is only in statically built sites that we need to do this.
> Hmmmm. if the plugin creates the right matches during a live run why 
> doesn't cocoon copy the files when generating statically? The files are 
> linked through <link...> elements in the head.

Err, then it's something that needs fixing, if it's linked it should 
pick it up.

Nicola Ken Barozzi         
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)

View raw message