forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject versioned plugin docs (Was: svn commit: r190111)
Date Mon, 13 Jun 2005 06:29:03 GMT
Ross Gardler wrote:
> 
> Sorry about not getting back sooner, I've been away for the weekend. 
> Fortunately this is a site issue so can be fixed after the code freeze 
> is lifted, just as long as the docs work on release day (which I believe 
> they will).

Yes it is only a "site/docs" issue. I reckon that this work can continue
throughout the code-freeze because it doesn't affect the function of
Forrest at all. WDOT?

> Ross Gardler wrote:
> > Ferdinand Soethe wrote:
> >
> >>Plugin docs should be versioned.
> >
> >I agree for all the reasons you have mentioned.
> >
> >>Different plugin releases may work in different versions of Forrest. For
> >>example, Daisy 0.1 works in 0.7, but 0.2 will not work in 0.7 Forrest
> >>because it relies on the locationmap.
> >
> >Yet I don't think that they should be part of Forrests versioned
> >info for several reasons:
> >
> >- Forrest and Plug-ins each have their own release cylces and we may well
> >  have a number of new plug-in versions during one Forrest release.
> >  So even though there is a relation between plug-in and Forrest
> >  version, it is of the kind
> >
> >        Plugin X.Y.Z works with Forrest A.B.C
> >
> >  and neither direct nor permanent.
> >
> >- Because of this, there will be frequent updated of plug-in
> >  information while we will have very little of non changes at all to
> >  the docs about past releases.
> 
> When a plugin is released its documents are uploaded to the live site 
> via SVN by the plugin build system. There is no manual intervention and 
> no connection between the Forrest docs and the plugin docs other than 
> links in tabs.xml an site.xml. In other words, each individual set of 
> plugin docs are managed independently of the Forrest site. They just 
> happen to be housed on the same web server in this case.

Yes, they are stored in the forrest/site SVN and automatic 'svn update'
checks them out on the web server. So they are not in the local site-author
space. The latter has full URLs to apache.org for plugin docs. That should
still work the same, just different URLs.

> As I mentioned in my original mail, moving the docs in SVN like this 
> breaks this plugin docs publishing mechanism since next time a plugin is 
> deployed its docs will be put in the wrong location for your current 
> site structure.
> 
> Something has to change, either this commit is reverted, or the plugin 
> build system is changed to publish into the root directory to match this 
> new structure.

I reckon that is best.

> Since I don't pretend to understand the way our versioned docs work I am 
> hesitant to change the build system since this is ow David asked me to 
> do it to make it work. If something has change then I need to know what, 
> but currently I believe this commit breaks things. Read on for 
> clarification.

Ah, that requested directory was because that was for the workaround
to solve the FOR-514 "Website/docs split". Hopefully we can find a
better solution.

> Ferdinand continued:
> >No problem there. I'd just solve it differently and have a general
> >access point through the PlugIn-Tab and deal with different versions
> >either by
> >
> >- having versioned sub tabs (in the Plug-In Tab) that lead to the version 
> >specific list of
> >  plug-ins and detailed info below that or
> >
> >- have a non versioned top level menu of all plug-ins and versioned
> >  submenus with the details below that.
> 
> We had a tab that points to the plugins docs, that tab used to point to 
> the relevant plugin docs for the version we were looking at. Just as the 
> How-To and other tabs work.
> 
> As for sub tabs for different versions this is inconsistent with the 
> behaviour of all other tabs. That is, we don't have 0.7 sub tabs for 
> How-To's and other tabs. Why do it for plugins?
> 
> Secondly, since you have moved the plugin docs into a non-versioned 
> directory how do you propose to provide different links (sub tabs or any 
> other method) to different versions, this change has removed all the 
> version information for the docs.

This issue is going to be hard to solve in email.

Perhaps Ferdinand had a good sleep and dreamed up a solution.
Anyway, lets talk more when he is back. I need to go now and
deal with the licensing and line-endings issues.

> (incidentally, this thread has made me realise a problem with versioned 
> plugin docs, but it is unrelated to this issue, and will only become a 
> problem when we deploy our first 0.8 only plugin. I'll address it then 
> rather than confuse this thread).

Good idea.

> >>Besides, these documents are auto published so just moving them in SVN
> >>will not help, next time the plugin is deployed the updated documets
> >>will go into the vesioned location again.
> >
> >A far as I understand the sitemap the list of plug-ins is generated
> >dynamically here
> >
> ><map:match pattern="docs/plugins/index.xml">
> >          <map:aggregate element="pluginList">
> >            <map:part src="{forrest:plugins-src}/plugins.xml"/>
> >            <map:part 
> >            src="{forrest:whiteboard-plugins-src}/whiteboard-plugins.xml"/>
> >          </map:aggregate>
> >          <map:transform src="{forrest:stylesheets}/plugins2xdoc.xsl"/>
> >          <map:serialize type="xml"/>
> >        </map:match>
> >
> >and works fine as long as the virtual index.html is in that
> >docs-directory. 
> 
> That is only the index page, which is generated from plugins.xml and 
> whiteboardPlugins.xml. It has nothing to do with the plugin docs themselves
> 
> {OT] In case you are wondering this page is generated dynamically so 
> that we can also include it in fresh-site without a deployed plugin 
> having to write to the Forest source tree.
> 
> > So everything works fine right now.
> 
> The index page will always work because it is dynamically generated.
> 
> As for the docs themselves it is my understanding that a request for 
> something like 
> http://forrest.apache.org/docs/plugins/org.apache.forrest.plugin.input.dtdx 
> (i.e. no version information) will be redirected to the current version 

We are doing that now with .htaccess and would need to tweak it on each
release. That is fine.

> and a request for 
> http://forrest.apache.org/0.8/docs/plugins/org.apache.forrest.plugin.input.dtdx 
> will be redirected to the 0.8 version docs. Consequently, the plugin docs 
> system was designed to publish the docs to the correct location based on 
> this versioned directory structure.

I think that this can still be done, just a slightly different structure.

-David

> If my understanding is correct we can achieve direct links to versioned 
> plugin docs. However, with the unversioned plugin docs you have created 
> here we cannot provide a versioned set of docs.
> 
> Ross

Mime
View raw message