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
