You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@forrest.apache.org by Arik Kfir <ar...@users.sourceforge.net> on 2005/03/15 23:08:05 UTC
Plugging into a site.xml
Hello,
We are writing software that utilizes Forrest and generates a complete
Forrest documentation project from some outside data. The only thing
that is provided from outside our software is the menu structure and
tabs (i.e. tabs.xml and site.xml) - they are provided by the user.
However, we need to manipulate them to insert some predefined menu
structure and tabs of our own.
For example, suppose the user provides a tabs.xml with custom tabs, the
resulting tabs.xml after processing should also contain our tabs as
well. The same for site.xml. Our dillema is: how should we perform the
manipulation? Of course, we can simply process the file directly and
change it (our copy of it, that is). But I was wondering if there is a
way of defining/redefining a pipeline or something in the project.xmap
that will so (perhaps create a custom Generator for the
site.xml/tabs.xml that will embed our added data).
Has anyone done this before (changing the default pipeline of
site.xml/tabs.xml) via the project's site map?
10x,
Arik.
Re: Plugging into a site.xml
Posted by Ross Gardler <rg...@apache.org>.
Arik Kfir wrote:
> Hello,
>
> We are writing software that utilizes Forrest and generates a complete
> Forrest documentation project from some outside data. The only thing
> that is provided from outside our software is the menu structure and
> tabs (i.e. tabs.xml and site.xml) - they are provided by the user.
> However, we need to manipulate them to insert some predefined menu
> structure and tabs of our own.
>
> For example, suppose the user provides a tabs.xml with custom tabs, the
> resulting tabs.xml after processing should also contain our tabs as
> well. The same for site.xml. Our dillema is: how should we perform the
> manipulation? Of course, we can simply process the file directly and
> change it (our copy of it, that is). But I was wondering if there is a
> way of defining/redefining a pipeline or something in the project.xmap
> that will so (perhaps create a custom Generator for the
> site.xml/tabs.xml that will embed our added data).
>
> Has anyone done this before (changing the default pipeline of
> site.xml/tabs.xml) via the project's site map?
Yes. You need what is called an Internal Plugin.
Input plugins can override any of the behaviour of Forrest (and can
break it so tread carefully). Note that plugins are only in the 0.7-dev
release, so you will need to be running SVN head version of Forrest, or
wait a few weeks for the o.7 release.
There is some documentation at
http://forrest.apache.org/docs/dev/plugins/pluginInfrastructure.html
The example given in that documentation is of the IMSManifest plugin,
which overrides site.xml behaviour and replaces it with a thing called
an IMS Manifest. You can use the same technique to generate your own
site.xml file from your external files.
Ask if you need help.
Ross
Re: Plugging into a site.xml
Posted by Sjur Moshagen <sj...@mac.com>.
På 16. mar. 2005 kl. 08.14 skrev Ferdinand Soethe:
> What I don't know/ haven't asked if this works with tabs as well, but
> you could always ask Sjur.
It does work, without problems. Actually, out present use of the
XInclude enhancements in site.xml and tabs.xml utilise XPointer (part
of XInclude) to extract fragments of an external file to create several
tabs. That is, we have all our external modifications in one file, but
extract once for each tab we want to add to tabs.xml. It looks like:
<!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab
V1.1//EN" "http://forrest.apache.org/dtd/tab-cocoon-v11.dtd">
<tabs title="Divvun" software="Divvun" copyright="Norgga Sámedikkis" >
<tab dir="" id="Home" label="Home" indexfile="index.html" >
<tab dir="" id="northern-sami" label="Davvisámegiella"
indexfile="index_sme.html" />
<tab dir="" id="lule-sami" label="Julevsámegiella"
indexfile="index_smi.html" />
<tab dir="" id="norwegian" label="Norsk"
indexfile="index_nb.html" />
<tab dir="" id="swedish" label="Svenska"
indexfile="index_sv.html" />
<tab dir="" id="finnish" label="Suomeksi"
indexfile="index_fi.html" />
</tab>
<tab id="adm" label="Administration" dir="adm"
indexfile="index.html" >
<tab id="adm-gen" label="General" dir="adm"
indexfile="index.html" />
<tab id="reports" label="Reports" dir="adm/reports"
indexfile="monthoverview.html" />
</tab>
<tab href="http://giellatekno.uit.no" label="Sami Disamb. Proj." />
<xi:include href="doc/tabs-frag.xml#xpointer(/tabs/tab[1])"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
<xi:include href="doc/tabs-frag.xml#xpointer(/tabs/tab[2])"
xmlns:xi="http://www.w3.org/2001/XInclude"/>
</tabs>
The external tabs file (named tabs-frag.xml in our case) looks like
this:
<tabs>
<tab dir="doc" id="TechDoc" label="Tech. doc" indexfile="intro.html" >
<tab dir="doc/admin" id="admin" label="Project"
indexfile="workplan.html" />
<tab dir="doc/admin/weekly" id="weekly" label="Weekly"
indexfile="index.html" />
<tab dir="doc/infra" id="infra" label="Infrastucture"
indexfile="workenvironment.html" />
<tab dir="doc/lang" id="lang" label="Languages"
indexfile="index.html" />
<tab dir="doc/ling" id="ling" label="Linguistics"
indexfile="common.html" />
<tab dir="doc/tools" id="tools" label="Tools"
indexfile="tools.html" />
</tab>
<tab id="how" label="HowTos" dir="doc" indexfile="howtos.html" />
</tabs>
Since the site.xml and its external extensions were quoted in
Ferdinand's e-mail, I won't repeat it here. But suffice to say that you
can include anything that is possible to express in XInclude, which
include the full power of XPointer, assuming that your XInclude
processor (ie the Cocoon XInclude processor) can handle it. I am not
aware of any limitations, but I haven't looked for them either.
Sjur
Re: Plugging into a site.xml
Posted by Ross Gardler <rg...@apache.org>.
Arik Kfir wrote:
> Indeed
>
> The plugin option does seem the most "elegant" - is the HEAD branch in a
> stable state that can be played with?
Yes, we are only a few weeks of release. In fact we always try and keep
head as stable as possible since many of the devs use it in live projects.
Ross
Re: Plugging into a site.xml
Posted by Arik Kfir <ar...@users.sourceforge.net>.
Indeed
The plugin option does seem the most "elegant" - is the HEAD branch in a
stable state that can be played with?
Ross Gardler wrote:
> Ferdinand Soethe wrote:
>
>> Hi Arik,
>>
>> AK> We are writing software that utilizes Forrest and generates a
>> complete
>> AK> Forrest documentation project from some outside data. The only thing
>> AK> that is provided from outside our software is the menu structure and
>>
>> Check out this example from a recent thread
>>
>> Q: Integrate multipage externally generated content
>>
>> It shows how to use x-include to insert buildingblocks into an
>> existing site.xml.
>
>
> This assumes you have a prebuilt site.xml snippet. This is not the
> case here, Arik has a different document format to start with and
> needs to translate it before it can be included. This will need to be
> dones with a transformation, therefore in internal plugin is the answer.
>
>> What I don't know/ haven't asked if this works with tabs as well, but
>> you could always ask Sjur.
>
>
> It does, but again, only if your snippet to include is already in the
> right format.
>
> Ross
>
>
Re: Plugging into a site.xml
Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
> Hi Arik,
>
> AK> We are writing software that utilizes Forrest and generates a complete
> AK> Forrest documentation project from some outside data. The only thing
> AK> that is provided from outside our software is the menu structure and
>
> Check out this example from a recent thread
>
> Q: Integrate multipage externally generated content
>
> It shows how to use x-include to insert buildingblocks into an
> existing site.xml.
This assumes you have a prebuilt site.xml snippet. This is not the case
here, Arik has a different document format to start with and needs to
translate it before it can be included. This will need to be dones with
a transformation, therefore in internal plugin is the answer.
> What I don't know/ haven't asked if this works with tabs as well, but
> you could always ask Sjur.
It does, but again, only if your snippet to include is already in the
right format.
Ross
Re: Plugging into a site.xml
Posted by Ross Gardler <rg...@apache.org>.
Arik Kfir wrote:
> Will this work in 0.6 as well?
>
[ref: XInclude in site.xml]
No, 0.7-dev only (and remember your included content must be in the
proper format for this to work at all).
Ross
Re: Plugging into a site.xml
Posted by Arik Kfir <ar...@users.sourceforge.net>.
Hi Ferdinand,
Will this work in 0.6 as well?
Ferdinand Soethe wrote:
>Hi Arik,
>
>AK> We are writing software that utilizes Forrest and generates a complete
>AK> Forrest documentation project from some outside data. The only thing
>AK> that is provided from outside our software is the menu structure and
>
>Check out this example from a recent thread
>
> Q: Integrate multipage externally generated content
>
>It shows how to use x-include to insert buildingblocks into an
>existing site.xml.
>
>What I don't know/ haven't asked if this works with tabs as well, but
>you could always ask Sjur.
>
>
>Sjur Moshagen <sj...@mac.com> wrote:
>
>
>
>>In site.xml:
>>
>><site xmlns="http://apache.org/forrest/linkmap/1.0" href=""
>>label="MyProj" tab="" >
>> <about label="Home" tab="Home" >
>> <index href="index.html" label="Index" description="Welcome
>>
>>
> divvun.no" />>
>
>
>> <changes href="changes.html" label="Changes" description="The
>>
>>
>ojects history" />>
>
>
>> <todo href="todo.html" label="Todo" description="The plan
>>
>>
>r the project" />>
>
>
>> </about>
>>
>> <xi:include href="doc/site-frag.xml#xpointer(/tech/*)"
>>xmlns:xi="http://www.w3.org/2001/XInclude"/>
>>
>></site>
>>
>>
>>In site-frag.xml:
>>
>><?xml version="1.0" encoding="UTF-8"?>
>><tech>
>> <techdoc href="doc/" label="Technical doc" tab="TechDoc">
>> <index href="intro.html" label="Introduction" />
>> </techdoc>
>> <!-- add entries ad lib just as in site.xml -->
>></tech>
>>
>>The same for tabs.xml and tabs-frag.xml.
>>
>>The outer element in both fragment files are required to make the files
>>valid XML files. Hence the reference to the content of that element in
>>the XInclude.
>>
>>It works like a charm, and having the full power of XInclude makes for
>>a very flexible solution.
>>
>>Sjur
>>
>>
>
>
>Regards
>Ferdinand Soethe
>
>
>
>
>
Re: Plugging into a site.xml
Posted by Ferdinand Soethe <sa...@soethe.net>.
Hi Arik,
AK> We are writing software that utilizes Forrest and generates a complete
AK> Forrest documentation project from some outside data. The only thing
AK> that is provided from outside our software is the menu structure and
Check out this example from a recent thread
Q: Integrate multipage externally generated content
It shows how to use x-include to insert buildingblocks into an
existing site.xml.
What I don't know/ haven't asked if this works with tabs as well, but
you could always ask Sjur.
Sjur Moshagen <sj...@mac.com> wrote:
> In site.xml:
>
> <site xmlns="http://apache.org/forrest/linkmap/1.0" href=""
> label="MyProj" tab="" >
> <about label="Home" tab="Home" >
> <index href="index.html" label="Index" description="Welcome
divvun.no" />>
> <changes href="changes.html" label="Changes" description="The
ojects history" />>
> <todo href="todo.html" label="Todo" description="The plan
r the project" />>
> </about>
>
> <xi:include href="doc/site-frag.xml#xpointer(/tech/*)"
> xmlns:xi="http://www.w3.org/2001/XInclude"/>
>
> </site>
>
>
> In site-frag.xml:
>
> <?xml version="1.0" encoding="UTF-8"?>
> <tech>
> <techdoc href="doc/" label="Technical doc" tab="TechDoc">
> <index href="intro.html" label="Introduction" />
> </techdoc>
> <!-- add entries ad lib just as in site.xml -->
> </tech>
>
> The same for tabs.xml and tabs-frag.xml.
>
> The outer element in both fragment files are required to make the files
> valid XML files. Hence the reference to the content of that element in
> the XInclude.
>
> It works like a charm, and having the full power of XInclude makes for
> a very flexible solution.
>
> Sjur
Regards
Ferdinand Soethe