You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@forrest.apache.org by Sjur Moshagen <sj...@mac.com> on 2005/01/12 15:16:17 UTC
Support for XInclude in tabs.xml and site.xml
Hello,
We are trying to make XInclude work in tabs.xml and site.xml, but we
don't succeed. Here's the background:
Two separate, but closely related projects share some documentation.
The two projects have their own documentation trees, but we want to
include the common documentation in both trees. The idea we came up
with was the following:
- have the common docs in a separate dir.
- have a sharedsite.xml and sharedtabs.xml in that dir
- copy in the dir into the doc. trees of each project
- use XInclude to include sharedsite.xml in site.xml, and
sharedtabs.xml in tabs.xml to create the complete site structure
But alas, we are not able to get XInclude to be processed in site.xml
and tabs.xml. Any ideas on how we can make the above setup (or a
similar one) run?
This was what we did:
<tabs>
<!-- other tabs go before here -->
<tab id="Technological" label="Technological documentation"
dir="xml-doc" indexfile="index.html">
<xi:include href="tullball.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
</tab>
</tabs>
Also this did not work:
<tabs>
<!-- other tabs go before here -->
<xi:include href="tullball.xml"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
</tabs>
Thanks for the help,
Sjur
Re: Support for XInclude in tabs.xml and site.xml
Posted by Sjur Moshagen <sj...@mac.com>.
På 18. jan. 2005 kl. 18.14 skrev Ross Gardler:
>>> Our solution is to import content from a repository.
>> This is also what we do.
>
> With one very important difference, for us, Forrest does it at
> runtime. There is no need for the content developers to import the
> docs, this is very important for us as most of our content developers
> are not technically aware, using a word processor is about their
> limit.
Ok.
>> I'll have to look into IMSManifest. Presently we (or I, that is:-)
>> would like to go for the XInclude solution, to get our site up and
>> running AFAP. That does not preclude that we also look into other
>> solutions that would also take care of repository checkouts/updates.
>
> Absolutely, you need to get things working for your project (and I
> will apply your patch since it does not affect other aspects of
> Forrest).
Thanks! :-)
> I just thought that we have an amount of overlap between our two use
> cases and wanted to explore that.
I agree there is overlap, and for a more solid long-term solution,
IMSManifest does definitely look interesting, cf. next paragraph.
> I suppose the real question I should be asking you is "would automatic
> management of included documents be a benefit in your case?"
Definitely.
>> One of our concerns would be i18n - we can only live with a solution
>> that integrates well with the i18n work done (and planned) in
>> Forrest.
>
> Well I have not done any work with i18n, but I see no reason why our
> own approach should br3eak this functionality since everything is
> converted to a site.xml and tabs.xml file and then handled internally
> by Forrest in exactly the same way.
Thanks for the clarification on IMSManifest's relation to site.xml and
tabs.xml
Sjur
Re: Support for XInclude in tabs.xml and site.xml
Posted by Ross Gardler <rg...@apache.org>.
Sjur Moshagen wrote:
> På 15. jan. 2005 kl. 18.05 skrev Ross Gardler:
>
>>> Do you see where we are heading? Does it make sense, or could there
>>> be better ways of doing it?
>>
>>
>> There are two other ways that we are aware of, but neither is fully
>> implemented as yet.
>>
>> The most complete solution is implemented in the IMSManifest block. It
>> has been agreed that it should be extracted to the core and made to
>> work in site.xml. It is in that block simply because the project
>> needing it was implemented using IMS Manifests.
>>
>> Our solution is to import content from a repository.
>
>
> This is also what we do.
With one very important difference, for us, Forrest does it at runtime.
There is no need for the content developers to import the docs, this is
very important for us as most of our content developers are not
technically aware, using a word processor is about their limit.
>> The big advantage of this is that Forrest automatically gets the
>> freshest content from the repository each time the site is built. Of
>> course, this is also a disadvantage as the site can't be built if we
>> don't have access to the repository (i.e. you need to be online).
>> Perhaps the answer is to have forrest checkout the remote content from
>> CVS/SVN as you do, it can manage the updates etc. locally.
>
>
> We should probably deal with the two issues separately:
>
> 1) flexible inclusion of what is wanted
> 2) update/checkout of the local copy
>
> 1) is very easily handled with XInclude - all xpath handling is already
> there.
With Forrest as it currently stands, XInclude is only sufficient if the
source is available locally. For us the repository could be anywhere.
> 2) I have no concrete suggestion on this one.
At present we use the document() function of XSLT to bring in the remote
document. This means we can provide a pipeline that pulls the data
from the relevant repository (here I am referring to CVS/SVN type
repositories for you and Learning Object repositories for myself). This
pipeline can be responsible for managing a local cache of the data.
>> I'd be happy to work with you on extracting this functionality to core
>> and enhancing it accordingly. It seems you have a similar use case to
>> mine.
>
>
> I'll have to look into IMSManifest. Presently we (or I, that is:-) would
> like to go for the XInclude solution, to get our site up and running
> AFAP. That does not preclude that we also look into other solutions that
> would also take care of repository checkouts/updates.
Absolutely, you need to get things working for your project (and I will
apply your patch since it does not affect other aspects of Forrest).
I just thought that we have an amount of overlap between our two use
cases and wanted to explore that. I suppose the real question I should
be asking you is "would automatic management of included documents be a
benefit in your case?"
> One of our concerns would be i18n - we can only live with a solution
> that integrates well with the i18n work done (and planned) in Forrest.
Well I have not done any work with i18n, but I see no reason why our own
approach should br3eak this functionality since everything is converted
to a site.xml and tabs.xml file and then handled internally by Forrest
in exactly the same way.
This means that improvements to the core i18n funcitonlaity should be
avilable to all solutions.
Ross
--
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.300 / Virus Database: 265.7.0 - Release Date: 17/01/2005
Re: Support for XInclude in tabs.xml and site.xml
Posted by Sjur Moshagen <sj...@mac.com>.
På 15. jan. 2005 kl. 18.05 skrev Ross Gardler:
>> Do you see where we are heading? Does it make sense, or could there
>> be better ways of doing it?
>
> There are two other ways that we are aware of, but neither is fully
> implemented as yet.
>
> The most complete solution is implemented in the IMSManifest block. It
> has been agreed that it should be extracted to the core and made to
> work in site.xml. It is in that block simply because the project
> needing it was implemented using IMS Manifests.
>
> Our solution is to import content from a repository.
This is also what we do.
> The big advantage of this is that Forrest automatically gets the
> freshest content from the repository each time the site is built. Of
> course, this is also a disadvantage as the site can't be built if we
> don't have access to the repository (i.e. you need to be online).
> Perhaps the answer is to have forrest checkout the remote content from
> CVS/SVN as you do, it can manage the updates etc. locally.
We should probably deal with the two issues separately:
1) flexible inclusion of what is wanted
2) update/checkout of the local copy
1) is very easily handled with XInclude - all xpath handling is already
there.
2) I have no concrete suggestion on this one.
> I'd be happy to work with you on extracting this functionality to core
> and enhancing it accordingly. It seems you have a similar use case to
> mine.
I'll have to look into IMSManifest. Presently we (or I, that is:-)
would like to go for the XInclude solution, to get our site up and
running AFAP. That does not preclude that we also look into other
solutions that would also take care of repository checkouts/updates.
> The second techniques for this is the linkmap. This is Nicola Ken's
> baby. If I understand correctly one of the benefits of this is that
> the location of files is not fixed, the linkmap points forrest in the
> right direction.
>
> I'll have to let someone else fill us in on exactly how this works and
> how much overlap there is with the above as I was elsewhere when that
> particular discussion was had.
I'll have to look into this one as well.
One of our concerns would be i18n - we can only live with a solution
that integrates well with the i18n work done (and planned) in Forrest.
The XInclude solution is ok - it presents the complete menu structure
to the i18n stage. The drawback is that all l10n strings would be
project specific (in src/documentation/translations/), unless we
implement a similar feature to the above for shared terminology, to
localise menus and tabs coming from the shared documentation.
Sjur
Re: Support for XInclude in tabs.xml and site.xml
Posted by Ross Gardler <rg...@apache.org>.
Sjur Moshagen wrote:
> 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:
<snip>
OK, I get it now. Thanks for the clarification.
> Do you see where we are heading? Does it make sense, or could there be
> better ways of doing it?
There are two other ways that we are aware of, but neither is fully
implemented as yet.
The most complete solution is implemented in the IMSManifest block. It
has been agreed that it should be extracted to the core and made to work
in site.xml. It is in that block simply because the project needing it
was implemented using IMS Manifests.
Our solution is to import content from a repository. At the moment out
repository is just a flat file structure accessible via http, but it
could, of course, be any suitable repository. The root of our repository
is http://www.burrokeet.org/repositoryData/ If you were to visit there
you would see that it is just a load of Forrest sites (each uses
IMSManifest rather than site.xml but that is not significant).
Within some of these sites there are special URI's that tell Forrest
that they should look elsewhere for the actual source files. We use a
URI because IMS Manifest does not provide a mechanism for inclusion,
however when porting to site.xml we could introduce a new element, for
example:
<include repository="URL_of_repository"
package="name_of_package"
xpath="path_of_segment"/>
This would extract the indicated segment (xpath) from the named package
(package) located in the indicated repository. Forrest is aware that the
contents are not from the local document tree and pulls them from
repository as needed.
At present it is only possible to include the whole of another site, I
have not implemented the xpath part, but this should be a small matter
of modifying the XSL.
I'd like to point at the viewSVN urls for the relevant content, but it
is down right now. To see how it is done take a look in
FORREST_HOME/plugins/IMSManifest/resources/stylesheets/imsmanifest2site.xml
(search for "repository")
The big advantage of this is that Forrest automatically gets the
freshest content from the repository each time the site is built. Of
course, this is also a disadvantage as the site can't be built if we
don't have access to the repository (i.e. you need to be online).
Perhaps the answer is to have forrest checkout the remote content from
CVS/SVN as you do, it can manage the updates etc. locally.
I'd be happy to work with you on extracting this functionality to core
and enhancing it accordingly. It seems you have a similar use case to mine.
---
The second techniques for this is the linkmap. This is Nicola Ken's
baby. If I understand correctly one of the benefits of this is that the
location of files is not fixed, the linkmap points forrest in the right
direction.
I'll have to let someone else fill us in on exactly how this works and
how much overlap there is with the above as I was elsewhere when that
particular discussion was had.
Ross
--
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.300 / Virus Database: 265.6.11 - Release Date: 12/01/2005
Re: Support for XInclude in tabs.xml and site.xml
Posted by Sjur Moshagen <sj...@mac.com>.
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
Re: Support for XInclude in tabs.xml and site.xml
Posted by Ross Gardler <rg...@apache.org>.
Sjur Moshagen wrote:
> På 12. jan. 2005 kl. 16.44 skrev Ross Gardler:
>
>> The site.xml and tabs.xml pipelines do not use the xinclude
>> transformer. I don't think there would be a problem in adding this
>> functionality to core, but you could create a project sitemap that
>> overrides the existing site.xml.
>>
>> There are three locations in which site.xml appears in the generate
>> portion of a pipeline, if you add
>>
>> <snip/>
>>
>> Do the same for the one location tabs.xml appears in a generate
>> section of a pipeline.
>>
>> This should work, if it does, please provide a patch and add it to our
>> issue tracker (see http://forrest.apache.org/contrib.html#patch )
>
>
> 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.
Ross
--
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.300 / Virus Database: 265.6.11 - Release Date: 12/01/2005
Re: Support for XInclude in tabs.xml and site.xml
Posted by Sjur Moshagen <sj...@mac.com>.
På 12. jan. 2005 kl. 16.44 skrev Ross Gardler:
> The site.xml and tabs.xml pipelines do not use the xinclude
> transformer. I don't think there would be a problem in adding this
> functionality to core, but you could create a project sitemap that
> overrides the existing site.xml.
>
> There are three locations in which site.xml appears in the generate
> portion of a pipeline, if you add
>
> <snip/>
>
> Do the same for the one location tabs.xml appears in a generate
> section of a pipeline.
>
> This should work, if it does, please provide a patch and add it to our
> issue tracker (see http://forrest.apache.org/contrib.html#patch )
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.
Regards,
Sjur N. Moshagen
Re: Support for XInclude in tabs.xml and site.xml
Posted by Ross Gardler <rg...@apache.org>.
Sjur Moshagen wrote:
> This was what we did:
>
> <tabs>
> <!-- other tabs go before here -->
> <tab id="Technological" label="Technological documentation"
> dir="xml-doc" indexfile="index.html">
> <xi:include href="tullball.xml"
> xmlns:xi="http://www.w3.org/2001/XInclude"/>
> </tab>
> </tabs>
>
> Also this did not work:
>
> <tabs>
> <!-- other tabs go before here -->
> <xi:include href="tullball.xml"
> xmlns:xi="http://www.w3.org/2001/XInclude"/>
> </tabs>
The site.xml and tabs.xml pipelines do not use the xinclude transformer.
I don't think there would be a problem in adding this functionality to
core, but you could create a project sitemap that overrides the existing
site.xml.
There are three locations in which site.xml appears in the generate
portion of a pipeline, if you add
<map:transform type="xinclude"/>
After the generation, e.g.
<map:match pattern="abs-linkmap">
<map:generate src="{project:content.xdocs}site.xml" />
<map:transform type="xinclude"/>
<map:transform
src="{forrest:stylesheets}/absolutize-linkmap.xsl" />
<map:serialize type="xml" />
</map:match>
Do the same for the one location tabs.xml appears in a generate section
of a pipeline.
This should work, if it does, please provide a patch and add it to our
issue tracker (see http://forrest.apache.org/contrib.html#patch )
Ross
--
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.300 / Virus Database: 265.6.10 - Release Date: 10/01/2005