forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <>
Subject Re: Include mechanism for forrest...
Date Mon, 17 Oct 2005 08:56:11 GMT
Erik Brakkee wrote:
> As I see it it just revolves around usability issues. See below.

OK, I'll reread and summarise from a user perspective...

> I have recently introduced Forrest at my work to generate documentation 
> and it is really a big hit, with especially the include feature being 
> really useful. Some of our documents tend to get big and splitting them 
> up makes it so much easier. If I would force my users to write the 
> <xi:include> markup above, I would have had a great problem getting it 
> accepted.

I'm still not convinced of the whole value of this extension, but I am 
convinced of some of the usability issues you raise. This makes the 
extension valuable in some use cases.

My biggest concern is that it is yet another processing step that every 
single document must go through before being output. This is going to 
have quite an impact on our performance, something we are taking more 
notice of as we get closer to a 1.0 release.

 From a usability perspective the automatic fallback is not a good thing 
in my opinion. Most users do not want Forrest to hide the fact that 
there is a problem with their generated site. Quite the reverse, they 
rely on Forrest to validate that all content is present and correct. 
However, I guess this could be made configurable:

<include src="myfile.xml" fallback="false"/>

The easier specification of what is to be included is nice and I see 
extensions to it, for example, include only a section:

<include src="myfile.xml" section="sectionID"/>

Not requiring paths relative to root is a great enhancement of current 


These advantages only apply to the small number of users wishing to 
include external documents I don't think these advantages are worth the 
performance hit we would get if we put it into core. That being said, I 
think this is a great candidate for an internal plugin. This will make 
it much easier for users who do lots of inclusion work to get this 
functionality, whilst leaving those concerned about performance to use 
the existing XInclude functionality.

I'm +1 on this becoming an internal plugin, so that it can be used by 
those who need it, but -0 on it being a core part of Forrest.



View raw message