forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sjur Moshagen <sju...@mac.com>
Subject Re: Support for XInclude in tabs.xml and site.xml
Date Sat, 15 Jan 2005 00:34:45 GMT
På 14. jan. 2005 kl. 15.57 skrev Ross Gardler:

> Sjur Moshagen wrote:
>> Thanks for the help, it worked.
>> A new issue is created in the issue tracker, together with a patch. 
>> Please see:
>> http://issues.cocoondev.org//browse/FOR-417
>> What's still left: to document the new xinclude function in site.xml 
>> and tabs.xml, both that it is there, and a simple example on how to 
>> use it.
>
> Yeah I saw that, thanks very much for the patch.
>
> I was about to commit it the other day but something struck me and I 
> don't currently have the time to check it out. Perhaps you could 
> explain how it works.
>
> My problem is understanding how this is helpful because all the XDocs 
> would have to be in the same directory structure. And since we can 
> only have one site.xml and one tabs.xml file in each project I'm not 
> sure how you are making multiple sites. Perhaps a brief example would 
> make the penny drop for me.

Here's our background in more detail:

- we have an existing project A with internal technical documentation
- the existing project has an external site that we are about to 
convert to Forrest; the external site has its own document tree, but we 
want to include the tech docs in the final site
- a new project B has started, building on top of project A
- project B needs its own external pages and external identity
- because project B uses most of the resources of project A, we want to 
include the tech docs of proj A in the resulting site of proj. B

How this is organised in CVS:
CVSROOT/proj-A/techdocs/foo.xml
                         site-frag.xml
                         tabs-frag.xml
                         [other xml docs ad lib]

         A-ext/[forrest-dir-struct]/xdocs/index.xml
                                          tabs.xml
                                          site.xml
                                          [other pages on the A site]

         B-ext/[forrest-dir-struct]/xdocs/index.xml
                                          tabs.xml
                                          site.xml
                                          [other pages on the B site]

Within the xdocs dir of each project, we check out the techdocs dir, 
such that it becomes a subdir of xdocs (but originating in a different 
CVS module), thus:

                                          techdocs/foo.xml
                                                   site-frag.xml
                                                   tabs-frag.xml

The files site-frag.xml and tabs-frag.xml contains the fragments for 
site.xml and tabs.xml relevant to the techdir module only. By using 
xinclude, we are now able to create a complete site for both projects 
containing the shared technical documentation, without having to worry 
about duplicates, syncronisation, and other issues if we had to 
maintain to synchronised documenation trees (or skip the tech docs in 
one of the projects).

What we DO still have to worry about, is to make sure that the shared 
documentation is organised acceptably to both projects, which we would 
have to do anyway since we are so closely related.

There is still quite some room for variation within each project: since 
we have the full power of xinclude, we can actually choose to include 
only portions of the site-frag.xml and tabs-frag.xml files at select 
locations in site.xml and tabs.xml. This way we can reorganise the 
menus and tabs of the shared documentation, or create the illusion that 
we only include some of the technical docs (skipping the parts not 
relevant to one of the projects).

I am very happy with the end result so far:-)

Do you see where we are heading? Does it make sense, or could there be 
better ways of doing it?

Sjur


Mime
View raw message