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
