forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: svn commit: r190111 - /forrest/branches/docs_reorg_200506_branch/site-author/content/xdocs/docs/plugins /forrest/branches/docs_reorg_200506_branch/site-author/content/xdocs/docs_0_70/plugins
Date Sun, 12 Jun 2005 20:51:09 GMT
Ferdinand Soethe 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).

Comments inline...

> Ross Gardler 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.

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.

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.

> 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.

(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).

>>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 
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.

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