You are viewing a plain text version of this content. The canonical link for it is here.
Posted to svn@forrest.apache.org by fe...@apache.org on 2005/06/11 14:30:26 UTC
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
Author: ferdinand
Date: Sat Jun 11 05:30:26 2005
New Revision: 190111
URL: http://svn.apache.org/viewcvs?rev=190111&view=rev
Log:
Move plugins back to docs because they should not be versioned
Added:
forrest/branches/docs_reorg_200506_branch/site-author/content/xdocs/docs/plugins/
- copied from r190105, forrest/branches/docs_reorg_200506_branch/site-author/content/xdocs/docs_0_70/plugins/
Removed:
forrest/branches/docs_reorg_200506_branch/site-author/content/xdocs/docs_0_70/plugins/
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by Ferdinand Soethe <sa...@soethe.net>.
Ross Gardler wrote:
> go with is one that has already been discussed on this list, but
> nevertheless, a summary is appropriate.
Thanks for your help in fixing and documenting that last remaining
problem. This is going to be a great and very useful improvement to
the plugin docs.
> http://f.a.o/docs/ will refer to the docs for current version of Forrest
This is the only correction a have. All versioned docs including the
current release will be in a pathname with their releasenumber. That
also ensured permanent urls for google and references in our mailing
lists.
--
Ferdinand Soethe
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by Ross Gardler <rg...@apache.org>.
David Crossley wrote:
> Ross Gardler wrote:
...
>>>Also there are two other docs referred to on its menu:
>>>usingPlugins.html
>>>pluginInfrastructure.html
>>>
>>>Should those two documents be also inside /pluginDocs/plugins_0_70/
>>>because they may change over time.
..
>>I suppose they could go into the versioned plugin docs directories.
>
>
> Okay, that is all done now in the trunk.
>
> The "Versioned Docs" and "Plugins" tabs both suffer from FOR-209
> where the main tabs are not higlighted when their subtabs are selected:
> http://issues.apache.org/jira/browse/FOR-209
>
> The plugins lists are both the same for:
> /pluginDocs/plugins_0_70/index.html
> /pluginDocs/plugins_0_80/index.html
> so we still need to fix the sitemap/stylesheet for that.
There are currently no 0.8 plugins, but there will be when we merge the
locationmap branch. It's just a simple filter in the stylesheet. I'll
address that when the merge happens and I have data to test it against.
In the meantime it is correct to have the 0.7 plugins in the 0.8 list as
it is a minimum required version rather than an actual required version.
Ross
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> David Crossley wrote:
> >David Crossley wrote:
> >
> >>Summarising ...
> >>
> >>http://f.a.o/docs_0_60/ will refer to the documentation for Forrest V0.6
> >>http://f.a.o/docs_0_70/ will refer to the documentation for Forrest V0.7
> >>http://f.a.o/docs_0_80/ will refer to the documentation for Forrest V0.8
> >>
> >>There will no longer be the "current version" at f.a.o/docs/
> >>
> >>Assuming that FOR-544 goes ahead:
> >>
> >>http://f.a.o/pluginDocs/plugins_0_70/index.html will be the index of
> >>valid plugins for the 0.7 version of Forrest
> >>http://f.a.o/pluginDocs/plugins_0_80/index.html will be the index of
> >>valid plugins for the 0.8 version of Forrest
> >>
> >>http://f.a.o/pluginDocs/plugins_0_70/PLUGINNAME will be the latest docs
> >>for the most recent release of the indicated plugin for version 0.7 of
> >>Forrest
> >>http://f.a.o/pluginDocs/plugins_0_80/PLUGINNAME will be the latest docs
> >>for the most recent release of the indicated plugin for version 0.8 of
> >>Forrest
> >
> >Now i have a question about the "Plugins" tab of the documentation as shown
> >in release candidate rc1 and of course the current trunk.
> >
> >It currently points to /docs/plugins/index.html and shows the plugins that
> >are
> >available for the current release. So does that now need to be changed to
> >be
> >rather /pluginDocs/plugins_0_70/index.html ?
> >
> >Also there are two other docs referred to on its menu:
> >usingPlugins.html
> >pluginInfrastructure.html
> >
> >Should those two documents be also inside /pluginDocs/plugins_0_70/
> >because they may change over time.
>
> index.xml is generated dynamically in sitemap.xmap from the plugins.xml
> file. This can go anywhere as long as the match is changed in sitemap.xmap
>
> The two others are Forrest documents and in my opinion should be
> versioned. They were in the versioned documents but Ferdinand moved them
> out and I gave up trying to convince him they should be left in since he
> had many other more important distractions at the time.
>
> I suppose they could go into the versioned plugin docs directories.
Okay, that is all done now in the trunk.
The "Versioned Docs" and "Plugins" tabs both suffer from FOR-209
where the main tabs are not higlighted when their subtabs are selected:
http://issues.apache.org/jira/browse/FOR-209
The plugins lists are both the same for:
/pluginDocs/plugins_0_70/index.html
/pluginDocs/plugins_0_80/index.html
so we still need to fix the sitemap/stylesheet for that.
-David
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by Ross Gardler <rg...@apache.org>.
David Crossley wrote:
> David Crossley wrote:
>
>>Summarising ...
>>
>>http://f.a.o/docs_0_60/ will refer to the documentation for Forrest V0.6
>>http://f.a.o/docs_0_70/ will refer to the documentation for Forrest V0.7
>>http://f.a.o/docs_0_80/ will refer to the documentation for Forrest V0.8
>>
>>There will no longer be the "current version" at f.a.o/docs/
>>
>>Assuming that FOR-544 goes ahead:
>>
>>http://f.a.o/pluginDocs/plugins_0_70/index.html will be the index of valid plugins
>>for the 0.7 version of Forrest
>>http://f.a.o/pluginDocs/plugins_0_80/index.html will be the index of valid plugins
>>for the 0.8 version of Forrest
>>
>>http://f.a.o/pluginDocs/plugins_0_70/PLUGINNAME will be the latest docs for the most
>>recent release of the indicated plugin for version 0.7 of Forrest
>>http://f.a.o/pluginDocs/plugins_0_80/PLUGINNAME will be the latest docs for the most
>>recent release of the indicated plugin for version 0.8 of Forrest
>
>
> Now i have a question about the "Plugins" tab of the documentation as shown
> in release candidate rc1 and of course the current trunk.
>
> It currently points to /docs/plugins/index.html and shows the plugins that are
> available for the current release. So does that now need to be changed to be
> rather /pluginDocs/plugins_0_70/index.html ?
>
> Also there are two other docs referred to on its menu:
> usingPlugins.html
> pluginInfrastructure.html
>
> Should those two documents be also inside /pluginDocs/plugins_0_70/
> because they may change over time.
index.xml is generated dynamically in sitemap.xmap from the plugins.xml
file. This can go anywhere as long as the match is changed in sitemap.xmap
The two others are Forrest documents and in my opinion should be
versioned. They were in the versioned documents but Ferdinand moved them
out and I gave up trying to convince him they should be left in since he
had many other more important distractions at the time.
I suppose they could go into the versioned plugin docs directories.
Ross
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by David Crossley <cr...@apache.org>.
David Crossley wrote:
> Summarising ...
>
> http://f.a.o/docs_0_60/ will refer to the documentation for Forrest V0.6
> http://f.a.o/docs_0_70/ will refer to the documentation for Forrest V0.7
> http://f.a.o/docs_0_80/ will refer to the documentation for Forrest V0.8
>
> There will no longer be the "current version" at f.a.o/docs/
>
> Assuming that FOR-544 goes ahead:
>
> http://f.a.o/pluginDocs/plugins_0_70/index.html will be the index of valid plugins
> for the 0.7 version of Forrest
> http://f.a.o/pluginDocs/plugins_0_80/index.html will be the index of valid plugins
> for the 0.8 version of Forrest
>
> http://f.a.o/pluginDocs/plugins_0_70/PLUGINNAME will be the latest docs for the most
> recent release of the indicated plugin for version 0.7 of Forrest
> http://f.a.o/pluginDocs/plugins_0_80/PLUGINNAME will be the latest docs for the most
> recent release of the indicated plugin for version 0.8 of Forrest
Now i have a question about the "Plugins" tab of the documentation as shown
in release candidate rc1 and of course the current trunk.
It currently points to /docs/plugins/index.html and shows the plugins that are
available for the current release. So does that now need to be changed to be
rather /pluginDocs/plugins_0_70/index.html ?
Also there are two other docs referred to on its menu:
usingPlugins.html
pluginInfrastructure.html
Should those two documents be also inside /pluginDocs/plugins_0_70/
because they may change over time.
-David
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by David Crossley <cr...@apache.org>.
Summarising ...
http://f.a.o/docs_0_60/ will refer to the documentation for Forrest V0.6
http://f.a.o/docs_0_70/ will refer to the documentation for Forrest V0.7
http://f.a.o/docs_0_80/ will refer to the documentation for Forrest V0.8
There will no longer be the "current version" at f.a.o/docs/
Assuming that FOR-544 goes ahead:
http://f.a.o/pluginDocs/plugins_0_70/index.html will be the index of valid plugins
for the 0.7 version of Forrest
http://f.a.o/pluginDocs/plugins_0_80/index.html will be the index of valid plugins
for the 0.8 version of Forrest
http://f.a.o/pluginDocs/plugins_0_70/PLUGINNAME will be the latest docs for the most
recent release of the indicated plugin for version 0.7 of Forrest
http://f.a.o/pluginDocs/plugins_0_80/PLUGINNAME will be the latest docs for the most
recent release of the indicated plugin for version 0.8 of Forrest
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by Ross Gardler <rg...@apache.org>.
Ross Gardler wrote:
> David Crossley wrote:
>
>> David Crossley wrote:
>
>
> ..
>
>>>> 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.
>>
>>
>>
>> We were hoping that we could solve this today, but it seems that Ross
>> is busy
>> on other things. We can attend to this later, as building the release is
>> not dependent on the deploying of the versioned plugins docs.
...
> All I need to know at this stage is what directory should the plugin
> docs be published to on the website SVN server. I will change the plugin
> build script accordingly and publish all plugins in order to republish
> the docs and deploy the versioned zips for download.
Given the timeframe of this Ferdinand, myself and David cheated today
and had a Skype conversation to confirm our collective understanding of
this thread. This mail is to summarise what was said for the benefit of
the community as a whole. As it happens, the solution we have decided to
go with is one that has already been discussed on this list, but
nevertheless, a summary is appropriate.
First let me summarise the problem:
Keeping versioned documents for plugins is difficult since there can be
multiple versions of the plugins and each version will work in one or
more version of Forrest. In addition guiding the user to the right page
with sensible navigation is a non-trivial issue.
We have decided to keep the plugins documentation completely separate
from the Forrest documentation. It is already conceptually separate in
that it is developed within the plugin itself and published
independently of Forrest. However, until the considerable efforts of
David and Ferdinand this weekend they were embedded within the versioned
docs for plugins. That is they were sub folders of the docs/0.7 or
docs/0.8 folders.
In this new documentation branch we will be publishing the plugin docs
to a separate directory structure. We will have one directory for each
major Forrest release (i.e. 0.7, 0.8, 0.9 and so on). Within each of
these directories there will be an index page showing the plugins that
are available for that version of Forrest.
The end result will be, for example:
http://f.a.o/docs/ will refer to the docs for current version of Forrest
http://f.a.o/docs_070/ will refer to the documentation for Forrest V0.7
http://f.a.o/plugins/index.html will be the index of valid plugins for
the current release version of Forrest
http://f.a.o/plugins_070/index.html will be the index of valid plugins
for the 0.7 version of Forrest
http://f.a.o/plugins_080/index.html will be the index of valid plugins
for the 0.8 version of Forrest
http://f.a.o/plugins_070/PLUGINNAME will be the latest docs for the most
recent release of the indicated plugin for version 0.7 of Forrest
http://f.a.o/plugins_080/PLUGINNAME will be the latest docs for the most
recent release of the indicated plugin for version 0.8 of Forrest
We decided against keeping *all* version docs for plugins since plugins
are small units of functionality and changes to plugins within a single
release of Forrest (i.e. no major changes to core) are unlikely to
result in major changes to a plugin. Where major changes to plugins are
likely to be seen is between versions of Forrest. For example, 0.7
Forrest does not have locationmap, 0.8 does. This is significantly
changing the way the Daisy plugin works between 0.7 and 0.8
To implement this I will need to make some minor changes to the plugin
build system and the plugins.xml file (these are only really config
changes). I will prepare a patch and call a vote against it since we are
currently in code freeze.
I hope that about covers it. I'm sure David or Ferdinand will
correct/clarify where necessary.
Whilst I am at it, can I take the opportunity to thank David and
Ferdinand. Trying to get these docs sensibly structured has been a major
task, one that I would not liked to have tackled. A round of applause
for our tireless housekeepers please...
Ross
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by Ross Gardler <rg...@apache.org>.
David Crossley wrote:
> David Crossley wrote:
..
>>>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.
>
>
> We were hoping that we could solve this today, but it seems that Ross is busy
> on other things. We can attend to this later, as building the release is
> not dependent on the deploying of the versioned plugins docs.
I'm afraid I've been with a client all morning. I'm back now, but am
happy to leave this issue on the backburner until after the release.
BOth David and Ferdinand seem to be aware of the problems and we all
seem to think the unversioned docs will work for release day, so no
problems.
All I need to know at this stage is what directory should the plugin
docs be published to on the website SVN server. I will change the plugin
build script accordingly and publish all plugins in order to republish
the docs and deploy the versioned zips for download.
Ross
Re: versioned plugin docs (Was: svn commit: r190111)
Posted by David Crossley <cr...@apache.org>.
David Crossley wrote:
> 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?
[ snip ]
> > 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.
>
> > 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.
We were hoping that we could solve this today, but it seems that Ross is busy
on other things. We can attend to this later, as building the release is
not dependent on the deploying of the versioned plugins docs.
--David
versioned plugin docs (Was: svn commit: r190111)
Posted by David Crossley <cr...@apache.org>.
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
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
Posted by Ross Gardler <rg...@apache.org>.
Ferdinand Soethe wrote:
>>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.
>
>
> Sorry, this probably a misunderstanding, I should have explained more.
> We all agree that that will have to be a versioned doc structure for
> plugins. David and I only wanted them in a different place than the
> normal versions docs.
>
> Something like
>
> xdocs
> docs_0_70
> docs_0_60
> ...
> plugins_0_70
> plugins_0_60
> ...
>
> Which should, as far as I can tell satisfy all the requirements and
> would only require minor changes. Am I mistaken her?
No that looks just fine, I just need to know where the plugin docs are
to be deployed to (see other mail).
> (Sorry for not being up to date with your new plugin publishing
> system.)
Bahhh!!!!
This hasn't change for at least a couple of months, don't you know *all*
our code yet????
(I don't think a smiley will be convey the level of sarcasm in the last
statement so I will shout it just in case I'M ONLY JOIKING ;-)
Ross
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
Posted by Ferdinand Soethe <sa...@soethe.net>.
Ross Gardler wrote:
> 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.
Yes, and there were good reasons to change that. So it might be useful
to see how we can adapt this to the new structure. Or put this in a
new thread and discuss if the new structure is not a good idea as such
(that's why it is still in a branch)
> 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?
Well it is consistent with the latest version and will be with my
first proposal to refine that:
1. Rename the main tab 'Docs' or 'Versioned Docs'
2. Move the current version (0.7) into a subtab just like all the
other versions and make that subtab the default selection when
selecting the main tab.
Which leaves two options for the plugins:
a) have them as a menu item within the 'Versioned Docs'-tab and thus
attach them to the Forrest version
OR
b) publish them into the subtabs of a separate main tab 'Plugins' that
will have subtabs for all Forrest versions.
I still prefer b) because - as you pointed out - the plugins are
really published independently from the Forrest release.
> 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.
I'm not sure I understand this one. As far as I recall there were only
three documents in that folder and we kept the 0.7 version with the
history. So in case we choose solution a), we can easily put them back
into the versioned docs, can't we.
> (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.
Looks like we could change it to publish to the new versioned structure
proposed above by just changing the target directories a bit?
> 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.
Sorry, this probably a misunderstanding, I should have explained more.
We all agree that that will have to be a versioned doc structure for
plugins. David and I only wanted them in a different place than the
normal versions docs.
Something like
xdocs
docs_0_70
docs_0_60
...
plugins_0_70
plugins_0_60
...
Which should, as far as I can tell satisfy all the requirements and
would only require minor changes. Am I mistaken her?
(Sorry for not being up to date with your new plugin publishing
system.)
Regards,
Ferdinand Soethe
--
Ferdinand Soethe
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
Posted by Ross Gardler <rg...@apache.org>.
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
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
Posted by Ferdinand Soethe <sa...@soethe.net>.
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.
> There are maor changes in the way
> it is used and so the docs need to be kept separate.
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.
Ideal would be a combination of these for different access to the info
like
Tab: PlugIns
Subtabs: [All] [Forrest 0.7] [Forrest 0.8] ...
Menus: Showing all or just that versions plug-ins depending on which
subtab is selected.
> 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. So everything works fine right now.
If there is new stuff I haven't had time to look at, lets talk about
how we can fix that.
Ferdinand
--
Ferdinand Soethe
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
Posted by Ross Gardler <rg...@apache.org>.
ferdinand@apache.org wrote:
> Author: ferdinand
> Date: Sat Jun 11 05:30:26 2005
> New Revision: 190111
>
> URL: http://svn.apache.org/viewcvs?rev=190111&view=rev
> Log:
> Move plugins back to docs because they should not be versioned
Plugin docs should be versioned.
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. There are maor changes in the way
it is used and so the docs need to be kept separate.
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.
Ross