forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [RT] Including Plugin documentation in Forrest website
Date Wed, 27 Oct 2004 18:14:27 GMT
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



Mime
View raw message