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
functionality.
However...
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.
WDOT?
Ross
