You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Ross Gardler <rg...@apache.org> on 2004/10/27 01:42:33 UTC
[RT] Including Plugin documentation in Forrest website
Background
==========
Way back in February I described a use case for building sites from
other sites. Nicola Ken joined the discussion saying he had a similar
need for the Incubator site. Now the issue seems to have arisen again
with the possible use of Forrest as an Apache wide publishing system.
The original thread starts at
http://marc.theaimsgroup.com/?l=forrest-dev&m=107652065930310&w=2
Nicola jumps in here
http://marc.theaimsgroup.com/?l=forrest-dev&m=107657256318416&w=2 (which
is where it starts to get focused, as usual ;-)
Why Now?
========
The need for this functionality is now upon Forrest itself. With the
creation of plugins it is now necessary to provide information on the
Forrest site about the available plugins.
We could maintain a list of plugins within src/documentation, but this
is wasteful as each plugin should come with its own documentation and
examples, so why duplicate effort? In addition it is hoped that other
projects will develop plugins for Forrest. We need a technique that
means we can automatically include details about their plugins on our
site without the need to maintain them ourselves.
Solution
========
The good news is I have a solution that is currently working (although a
little buggy)
(NB, if you read Nicola Kens post linked to above this implements
"1-subsite mounting")
Within the IMSManifest plugin is a mechanism for building sites that
contain other sites. The src for the site is placed in a repository.
This could be any kind of repository, XML database, webdav, SVN, website
etc. (although right now only website is supported). At build time the
IMSManifest of the site to be included is inserted into the parent site
structure. This aggregation is then used to build the site. The result
is a seemless integration of the two or more sites, in addition any
level of nesting of sites is supported.
For an example see http://www.burrokeet.org, everything under the
Documentation/BurrokeetHow-To menu item is from an included site from
the repository.
You can see the repository at http://www.burrokeet.org/repositoryData/
(see HowTo folder for sources, the main site sources are in the Website
folder).
The joining of the two sites is done through a special entry in the
IMSManifest file that indicates another site should be included. An URL
is used to indicate the repository to be used and the subsite to be
included from that repository.
The Way Forward
===============
1) Make the forrest site use IMSManifest plugin and use the embedding
functionality from there (the IMSManifest is not as friendly to edit as
site.xml and tabs.xml are automatically generated from it, which gives
less control over them)
2) Move this functionality into Forrest Core and make it work with
site.xml (as originally proposed in the two mails linked to above)
3) Move the functionality to its own plugin (again making it work with
site.xml)
4) some other method?...
I would prefer to see 2 happen (and am willing to do the work). It will
not break my IMSManifest plugin and will not break backward
computability. This is a very powerful feature that I believe deserves
to be in core, but I have no problem with implementing one of the other
solutions if that is what the consensus is.
Current Known Bugs/Limitations
==============================
- It is only possible to import whole sites (shouldn't be a problem to
add an XPATH statement to the URL that will select the nodes required)
- tab highlighting is broken (should be easily fixed, I just haven't got
around to it yet)
- I have not tested the impact on performance, I suspect Cocoons caching
will mean there is little impact, but I do not understand how the
caching works on Cocoon to be sure, and I have not tested this
Comments, questions, thoughts?
Ross
Re: [RT] Including Plugin documentation in Forrest website
Posted by Ross Gardler <rg...@apache.org>.
Diwaker Gupta wrote:
> On Wed, 27 Oct 2004 19:14:27 +0100, Ross Gardler <rg...@apache.org> wrote:
>
>>Am I still going in the wrong direction? I have no problem with it
>>staying in the IMSManifest plugin, just wanting to know if it has a
>>wider use.
>
>
> I think its a **great** thought, and will definitely go a long way in
> making Forrest a mature product. There are many many more use cases
> that can be thought of, but the ones you list make a representative
> list. But I'll add just another one:
>
> Consider the computer science department of a University. The systems
> people maintain their own webpage, the theory guys maintain their own
> (do they??!), the vision people their own. The CS webadmins then
> simply can use Forrest to plug-in these separate websites to create an
> integrated website for the department.
>
Funnily enough that is pretty much why it was created in the first
place. I had many departmetns sharing learning content across theire
staff, each wanted to present it with their own branding.
I'm awaiting a decision on a new contract that will do precisely what
you describe above. Can't believe I forgot that use case!
Ross
Re: [RT] Including Plugin documentation in Forrest website
Posted by Ross Gardler <rg...@apache.org>.
David Crossley wrote:
> Dave Brondsema wrote:
>
>>Ross Gardler wrote:
>>
>>>Dave Brondsema wrote:
>>>
>>>>Yeah I think it's a fine idea. Is it really related to IMSManifests?
>>>>Would it be better as it's own plugin? Or would it even be better
>>>>as part of core forrest.. I'm not sure how much change it would
>>>>require.
>>>>
>>>>But for our need of documenting plugins, lets go the simple route. If
>>>>we need to use this feature in the future, we can, but I don't see the
>>>>need now.
>>>
>>>I may just be being lazy here (not a good reason to force the point).
>>>The (minimal) docs I have written/copied for the plugins are already in
>>>the individual plugins. I think I may just be trying to avoid a little
>>>work ;-)
>>
>>Ooh, I see. Embedding documentation in the plugin .zip file is a good
>>idea, especially for ones that people develop & maintain outside of
>>forrest. And so all plugin documentation should follow the same pattern.
>
>
> Nice evolution of this Random Thought thread. Great stuff Ross.
> It looks like it is almost a reality. Go for it.
>
> Did you reckon it could be added to the core? If so, then
> i think that would be better.
If I can extract it from the IMSManifest it can go in core (I don't
perceive any technical obstacles to this). Personally I think it belongs
there, but I'll put it in a plugin first, if I succeed then we can cote
on its inclusion in core.
Ross
Re: [RT] Including Plugin documentation in Forrest website
Posted by David Crossley <cr...@apache.org>.
Dave Brondsema wrote:
> Ross Gardler wrote:
> > Dave Brondsema wrote:
> >> Yeah I think it's a fine idea. Is it really related to IMSManifests?
> >> Would it be better as it's own plugin? Or would it even be better
> >> as part of core forrest.. I'm not sure how much change it would
> >> require.
> >>
> >> But for our need of documenting plugins, lets go the simple route. If
> >> we need to use this feature in the future, we can, but I don't see the
> >> need now.
> >
> > I may just be being lazy here (not a good reason to force the point).
> > The (minimal) docs I have written/copied for the plugins are already in
> > the individual plugins. I think I may just be trying to avoid a little
> > work ;-)
>
> Ooh, I see. Embedding documentation in the plugin .zip file is a good
> idea, especially for ones that people develop & maintain outside of
> forrest. And so all plugin documentation should follow the same pattern.
Nice evolution of this Random Thought thread. Great stuff Ross.
It looks like it is almost a reality. Go for it.
Did you reckon it could be added to the core? If so, then
i think that would be better.
--
David Crossley
Re: [RT] Including Plugin documentation in Forrest website
Posted by Dave Brondsema <da...@brondsema.net>.
Ross Gardler wrote:
>
>
> Dave Brondsema wrote:
>
>> Diwaker Gupta wrote:
>>
>>> On Wed, 27 Oct 2004 19:14:27 +0100, Ross Gardler
>>> <rg...@apache.org> wrote:
>>>
>>>> Am I still going in the wrong direction? I have no problem with it
>>>> staying in the IMSManifest plugin, just wanting to know if it has a
>>>> wider use.
>>>
>>>
>>>
>>>
>>> I think its a **great** thought, and will definitely go a long way in
>>> making Forrest a mature product. There are many many more use cases
>>> that can be thought of, but the ones you list make a representative
>>> list. But I'll add just another one:
>>>
>>> Consider the computer science department of a University. The systems
>>> people maintain their own webpage, the theory guys maintain their own
>>> (do they??!), the vision people their own. The CS webadmins then
>>> simply can use Forrest to plug-in these separate websites to create an
>>> integrated website for the department.
>>>
>>> I'm +1 on the 2) approach -- this should be core forrest
>>> functionality. Further, I have a feeling that (like IMSManifest) any
>>> plugin that does this would not be able to provide fine grained
>>> control over site.xml and tabs.xml (atleast not easily).
>>>
>>
>> Yeah I think it's a fine idea. Is it really related to IMSManifests?
>> Would it be better as it's own plugin? Or would it even be better as
>> part of core forrest.. I'm not sure how much change it would require.
>
>
> I *think* I can extract it from the IMS Manifest plugin, its just that
> the project I built it for (don't worry I own the copyrights)we needed
> to use IMS Manifests, hence that is where it is at the moment.
>
Cool.
>> But for our need of documenting plugins, lets go the simple route. If
>> we need to use this feature in the future, we can, but I don't see the
>> need now.
>
>
> I may just be being lazy here (not a good reason to force the point).
> The (minimal) docs I have written/copied for the plugins are already in
> the individual plugins. I think I may just be trying to avoid a little
> work ;-)
>
> Ross
Ooh, I see. Embedding documentation in the plugin .zip file is a good
idea, especially for ones that people develop & maintain outside of
forrest. And so all plugin documentation should follow the same pattern.
--
Dave Brondsema : dave@brondsema.net
http://www.splike.com : programming
http://csx.calvin.edu : student org
http://www.brondsema.net : personal
Re: [RT] Including Plugin documentation in Forrest website
Posted by Ross Gardler <rg...@apache.org>.
Dave Brondsema wrote:
> Diwaker Gupta wrote:
>
>> On Wed, 27 Oct 2004 19:14:27 +0100, Ross Gardler <rg...@apache.org>
>> wrote:
>>
>>> Am I still going in the wrong direction? I have no problem with it
>>> staying in the IMSManifest plugin, just wanting to know if it has a
>>> wider use.
>>
>>
>>
>> I think its a **great** thought, and will definitely go a long way in
>> making Forrest a mature product. There are many many more use cases
>> that can be thought of, but the ones you list make a representative
>> list. But I'll add just another one:
>>
>> Consider the computer science department of a University. The systems
>> people maintain their own webpage, the theory guys maintain their own
>> (do they??!), the vision people their own. The CS webadmins then
>> simply can use Forrest to plug-in these separate websites to create an
>> integrated website for the department.
>>
>> I'm +1 on the 2) approach -- this should be core forrest
>> functionality. Further, I have a feeling that (like IMSManifest) any
>> plugin that does this would not be able to provide fine grained
>> control over site.xml and tabs.xml (atleast not easily).
>>
>
> Yeah I think it's a fine idea. Is it really related to IMSManifests?
> Would it be better as it's own plugin? Or would it even be better as
> part of core forrest.. I'm not sure how much change it would require.
I *think* I can extract it from the IMS Manifest plugin, its just that
the project I built it for (don't worry I own the copyrights)we needed
to use IMS Manifests, hence that is where it is at the moment.
> But for our need of documenting plugins, lets go the simple route. If
> we need to use this feature in the future, we can, but I don't see the
> need now.
I may just be being lazy here (not a good reason to force the point).
The (minimal) docs I have written/copied for the plugins are already in
the individual plugins. I think I may just be trying to avoid a little
work ;-)
Ross
Re: [RT] Including Plugin documentation in Forrest website
Posted by Dave Brondsema <da...@brondsema.net>.
Diwaker Gupta wrote:
> On Wed, 27 Oct 2004 19:14:27 +0100, Ross Gardler <rg...@apache.org> wrote:
>
>>Am I still going in the wrong direction? I have no problem with it
>>staying in the IMSManifest plugin, just wanting to know if it has a
>>wider use.
>
>
> I think its a **great** thought, and will definitely go a long way in
> making Forrest a mature product. There are many many more use cases
> that can be thought of, but the ones you list make a representative
> list. But I'll add just another one:
>
> Consider the computer science department of a University. The systems
> people maintain their own webpage, the theory guys maintain their own
> (do they??!), the vision people their own. The CS webadmins then
> simply can use Forrest to plug-in these separate websites to create an
> integrated website for the department.
>
> I'm +1 on the 2) approach -- this should be core forrest
> functionality. Further, I have a feeling that (like IMSManifest) any
> plugin that does this would not be able to provide fine grained
> control over site.xml and tabs.xml (atleast not easily).
>
Yeah I think it's a fine idea. Is it really related to IMSManifests?
Would it be better as it's own plugin? Or would it even be better as
part of core forrest.. I'm not sure how much change it would require.
But for our need of documenting plugins, lets go the simple route. If
we need to use this feature in the future, we can, but I don't see the
need now.
--
Dave Brondsema : dave@brondsema.net
http://www.splike.com : programming
http://csx.calvin.edu : student org
http://www.brondsema.net : personal
Re: [RT] Including Plugin documentation in Forrest website
Posted by Diwaker Gupta <di...@gmail.com>.
On Wed, 27 Oct 2004 19:14:27 +0100, Ross Gardler <rg...@apache.org> wrote:
> Am I still going in the wrong direction? I have no problem with it
> staying in the IMSManifest plugin, just wanting to know if it has a
> wider use.
I think its a **great** thought, and will definitely go a long way in
making Forrest a mature product. There are many many more use cases
that can be thought of, but the ones you list make a representative
list. But I'll add just another one:
Consider the computer science department of a University. The systems
people maintain their own webpage, the theory guys maintain their own
(do they??!), the vision people their own. The CS webadmins then
simply can use Forrest to plug-in these separate websites to create an
integrated website for the department.
I'm +1 on the 2) approach -- this should be core forrest
functionality. Further, I have a feeling that (like IMSManifest) any
plugin that does this would not be able to provide fine grained
control over site.xml and tabs.xml (atleast not easily).
--
Diwaker Gupta
http://resolute.ucsd.edu/diwaker
Re: [RT] Including Plugin documentation in Forrest website
Posted by Ross Gardler <rg...@apache.org>.
Dave Brondsema wrote:
> Ross Gardler wrote:
>
>> Background
>> ==========
>>
>> Way back in February I described a use case for building sites from
>> other sites. Nicola Ken joined the discussion saying he had a similar
>> need for the Incubator site. Now the issue seems to have arisen again
>> with the possible use of Forrest as an Apache wide publishing system.
>>
>> The original thread starts at
>> http://marc.theaimsgroup.com/?l=forrest-dev&m=107652065930310&w=2
>>
>> Nicola jumps in here
>> http://marc.theaimsgroup.com/?l=forrest-dev&m=107657256318416&w=2
>> (which is where it starts to get focused, as usual ;-)
>>
>> Why Now?
>> ========
>>
>> The need for this functionality is now upon Forrest itself. With the
>> creation of plugins it is now necessary to provide information on the
>> Forrest site about the available plugins.
>>
>> We could maintain a list of plugins within src/documentation, but this
>> is wasteful as each plugin should come with its own documentation and
>> examples, so why duplicate effort? In addition it is hoped that other
>> projects will develop plugins for Forrest. We need a technique that
>> means we can automatically include details about their plugins on our
>> site without the need to maintain them ourselves.
>>
>
> If we just want a simple page listing the available plugins and their
> descriptions, we can pull the info from plugins.xml and do a
> transformation to document-v13. This would be much like what we can do
> for integrating an RSS feed although the transformation details would be
> different.
Yes, that is what I was thinking of putting in fresh-site.
> (off-topic: we should probably make the plugins.xml DTD external)
(still off topic: +1, at the moment the plugins.xml is modeled on
skins.xml, if we generalise them I think we can use the same schema)
(back on topic) skins will need the same documentation generation system
> For full documentation pages of plugins that come available with
> forrest, I think we can just document those using regular pages as part
> of forrest's normal documentation.
Yes, we could, but my proposal allows us to include documentation from
plugins that are not housed in our SVN but are "endorsed" by us. In
addition, what if we have a plugin in our SVN but the committer of that
plugin are not committer on Forrest? By keeping the documentation for
the plugin we are not preventing some people writing docs for their own
project. I accept this may never happen, but then again, it may.
Furthermore, I believe this would be useful functionality for other
projects too (like ANT). Currently ANT maintains a list of known
extensions and tools (http://ant.apache.org/external.html), this has to
be manually maintained. Using this procedure all we/ANT would need to do
is maintain a list of such extensions (like our plugins.xml and
site.xml) and have the owning site store the src code for their
documentation in an accessible location.
The difference is that out plugins.xml file will retrieve details that
can change (such as description, latest version etc) from the plugin
project itself. We, as Forrest committer, need only add the name of the
plugin and the location it is to be found. The rest is automatic.
But there's more...
Sites like incubator, jakarta and XML where there are many sub-projects
each wanting to maintain their own sites could use this feature to
integrate the content of those sub-sites.
How about a third use case?
Apache has some documents (or should have) that are applicable across
all projects. For example, how to access SVN, Mailing List etiquette,
About Apache etc. Using this technique these content objects need only
be created once in the core repository then each project can include
them in their own site (with their own skin). Therefore the information
becomes more accessible and consequently more useful.
Am I still going in the wrong direction? I have no problem with it
staying in the IMSManifest plugin, just wanting to know if it has a
wider use.
Ross
Re: [RT] Including Plugin documentation in Forrest website
Posted by Dave Brondsema <da...@brondsema.net>.
Ross Gardler wrote:
> Background
> ==========
>
> Way back in February I described a use case for building sites from
> other sites. Nicola Ken joined the discussion saying he had a similar
> need for the Incubator site. Now the issue seems to have arisen again
> with the possible use of Forrest as an Apache wide publishing system.
>
> The original thread starts at
> http://marc.theaimsgroup.com/?l=forrest-dev&m=107652065930310&w=2
>
> Nicola jumps in here
> http://marc.theaimsgroup.com/?l=forrest-dev&m=107657256318416&w=2 (which
> is where it starts to get focused, as usual ;-)
>
> Why Now?
> ========
>
> The need for this functionality is now upon Forrest itself. With the
> creation of plugins it is now necessary to provide information on the
> Forrest site about the available plugins.
>
> We could maintain a list of plugins within src/documentation, but this
> is wasteful as each plugin should come with its own documentation and
> examples, so why duplicate effort? In addition it is hoped that other
> projects will develop plugins for Forrest. We need a technique that
> means we can automatically include details about their plugins on our
> site without the need to maintain them ourselves.
>
If we just want a simple page listing the available plugins and their
descriptions, we can pull the info from plugins.xml and do a
transformation to document-v13. This would be much like what we can do
for integrating an RSS feed although the transformation details would be
different.
(off-topic: we should probably make the plugins.xml DTD external)
For full documentation pages of plugins that come available with
forrest, I think we can just document those using regular pages as part
of forrest's normal documentation.
--
Dave Brondsema : dave@brondsema.net
http://www.splike.com : programming
http://csx.calvin.edu : student org
http://www.brondsema.net : personal