forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Erik Brakkee <e...@brakkee.org>
Subject Re: Include mechanism for forrest...
Date Sat, 15 Oct 2005 20:11:28 GMT
Hi Ross,

As I see it it just revolves around usability issues. See below.

Ross Gardler wrote:

> I don't actually see the need for this, your justification for using 
> this instead of XInclude is:
>
> 1  Adding XInclude elements to your document breaks the DTD so that 
> you can no longer validate your documents.
> 2 XInclude requires either full path names of files or files relative 
> to the root of the site. Unfortunately, the existing link rewriting in 
> Forrest generates links relative to the current file.
> 3 Typically you do not want to include the full contents of anothert 
> Xdoc document but only the content of the body tag. Using Xinclude 
> directly requires an author to write non-trivial XML with xpointer 
> expressions.
>
> Let me address each point:
>
> 1) Since the XInclude elements are in a different namespace you can 
> still validate your documents

If you add an element from another namespace to your document, you still 
must modify your DTD to accept this element. I still have to import 
other DTD declarations (found on the Forrest site) to avoid validation 
errors. I find this approach a bit cumbersome.  It would be better if 
the document type would support includes out of the box.

>
> 2) XInclude allows you to use any legal protocol in defining your URL. 
> This means you can use cocoon:, site: and ext: in 0.7 and can ad lm: 
> to that list in 0.8-dev Therefore you don't even need to know the name 
> of the file, just how to access it. Since this information is already 
> located somewhere in your site (for example, in site.xml) then you 
> have no problem forming a URL that is usable.

XInclude is used by the include extension. Nevertheless, direct use of 
XInclude is cumbersome. For instance, you always need to add a fallback 
element yourself, which the include extension does automatically, and 
you can work with references in the same way you do elsewhere. It should 
not be difficult to make sure that every protocol supported by XInclude 
is also supported by the include extension.

In my case, site: URLs did not work with XInclude because, as I recall, 
Xinclude processing takes place before link rewriting. Also, forcing the 
user to provide URLs relative to the site root is problematic. Sometimes 
you just want to include content from the same directory without 
defining all documents in the site.xml or referring to them with URLs 
relative to the site root.

>
> 3) XInclude allows you to select parts of a document using XPath 
> statements. This means you can include any part of the document you 
> can specifcy with an XPath expression.

I am using xinclude under the covers (of course) and I really believe 
that any include facility should be based on XInclude. But again, it is 
a usability problem. If a user includes a document  file.html into his 
document from the same directory as the document, then I
want to include the content from the xdoc file.xml and specifically the 
contents of the body tag. With the include extension, you simply write

    <include file="file.html/>

With XInclude you would have to write

    <xi:include href="cocoon:/pathtofile/file.xml#xpointer(//body/*)>
        <xi:fallback>
            <p>link to file.html not found </p>
        </xi:fallback>
    </xi:include>

Also, the xpointer support in Forrest is a bit minimal. You cannot 
specify the pointer attribute to xi:include (this is ignored), and it 
does not support full xpointer syntax, such as 'range-inside(body)'. 
Using an include tag allows you to hide dependencies on the specifics of 
the underlying xinclude processor.

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.

>
> see 
> http://cocoon.apache.org/2.1/userdocs/transformers/xinclude-transformer.html 
> for more information on the XInclude transformer.
>
> Am I misunderstanding the problem your extension is addressing, or do 
> we just need to document the XInclude features better?

It would definitely help to document the XInclude feature better, but I 
still think that from a usability point of view, a simple syntax should 
be provided for includes as part of the Xdoc DTD.. I think this is also 
in the spirit of forrest.

 From the home page of forrest:
/"Forrest is designed with the new user in mind.
Forrest's focus on low "startup cost" makes it ideal for rapid 
development of small sites, where time and budget constraints do not 
allow time-wasting HTML experiments. Of course, that same methodology 
can scale up to large projects. Your development team does not need Java 
experience, or even XML skills, to use Forrest. The framework lets you 
concentrate on content and design. "/

In other words, I think this is a good reason to add an include feature 
to Forrest.

Cheers
  Erik

>
> Ross



Mime
View raw message