forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ferdinand Soethe <samm...@soethe.net>
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 Mon, 13 Jun 2005 06:21:29 GMT




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


Mime
View raw message