Re: problem with docs at forrest.apache.org/docs/dev/
David Crossley wrote: Ross Gardler wrote: How do we link from the main docs-author (or site-author?) part of the site? If we use docs/plugins/ then it will intergrate easily. With the final scheme, we now need to put the generated plugins docs in the forrest/site repository under the /0.7/docs/plugins/ directory. --David
Re: problem with docs at forrest.apache.org/docs/dev/
David Crossley wrote: Ross Gardler wrote: David Crossley wrote: If they went under docs/plugins/$plugin-name/ then they will fit better with the versioning system described above. OK, that's where I'll put them then. Hmmm, but you put them under /plugins/docs/ instead? http://svn.apache.org/viewcvs?view=revrev=160244 That was before I asked the question. I was just testing that it worked. I'll clean up SVN and everything before doing the final release of all the plugins. Ross
Re: problem with docs at forrest.apache.org/docs/dev/
Dave Brondsema wrote: [snip] Furthering this idea, if we are versioning and storing docs-author and site-author, do we really need to store them seperately? As you said, this method would mean we won't have to restructure the forrest_06_branch docs into two parts. Good point. This separation is actually causing grief for the off-line docs, as we cannot link from one to the other. I looked back through the email threads on FOR-391 and it seems that we made an assumption leap to have the docs-author and site-author split. There was a passing comment that we might have it like Cocoon where they have a completely separate svn:cocoon/site/ to hold the top-level docs. We didn't talk about the consequences. So coming back to the current proposal, the only issue that i see is that we will have multiple versions of the top-level docs. I don't see that as a problem because we will have multiple versions of /docs/ anyway and they will have a banner saying this is version x.y. --David
Re: problem with docs at forrest.apache.org/docs/dev/
David Crossley wrote: David Crossley wrote: David Crossley wrote: David Crossley wrote: David Crossley wrote: [snip] Assuming that we don't want to version the top-level docs. Is that a legitimate assumption? It would change our layout if we do. I don't know the answer yet either. f.a.o/ ... the top-level docs, from trunk/site-author f.a.o/docs/ ... is .htaccess to redirect to current release docs. f.a.o/docs/0.6/ ... from the forrest_06_branch (*) f.a.o/docs/0.7/ ... from the forrest_07_branch, when it is released f.a.o/docs/0.8/ ... the next development, from future trunk/docs-author/ Let us see what the other solution would be. (Say that current release is 0.7) f.a.o/ ... the top-level docs, .htaccess to redirect to 0.7 top-level f.a.o/docs/ ... .htaccess to redirect to 0.7/docs/ f.a.o/0.6/ ... from the forrest_06_branch f.a.o/0.6/docs/ ... from the forrest_06_branch f.a.o/0.7/ ... from the forrest_07_branch/site-author/ f.a.o/0.7/docs/ ... from the forrest_07_branch/docs-author/ f.a.o/0.8/ ... the next development, from the trunk/site-author/ f.a.o/0.8/docs/ ... from the trunk/docs-author/ Ross Gardler wrote in another thread: Date: Mon Apr 4 15:13:48 2005 URL: http://svn.apache.org/viewcvs?view=revrev=160109 Log: Deployment of org.apache.forrest.plugin.OpenOffice.org plugin (deployed by 'deploy' target of plugin build script) Added: forrest/site/plugins/docs/org.apache.forrest.plugin.OpenOffice.org/ forrest/site/plugins/docs/org.apache.forrest.plugin.OpenOffice.org/skin/ forrest/site/plugins/docs/org.apache.forrest.plugin.OpenOffice.org/skin/screen.css OK, I'm experimenting with auto generating plugin docs, so you may see a few of these kinds of commits over then next week as I grab an hour here an hour there. But I have some questions. I've not really kept up to date with the docs discussions, either the first round or this round. I'm afraid they slipped underneath my full attention threshold. Now I find I should have kept up. How do people suggest I integrate the plugin docs with the main website docs? If they went under docs/plugins/$plugin-name/ then they will fit better with the versioning system described above. OK, that's where I'll put them then. I assume we want to SVN them into place in the way I've prototyped (see commit above), rather than duplicate the xdocs in the docs-author site. Note, that the point to link into these docs will therefore be docs/plugins/index.html. That page will contain a link to all the individual plugin documents. One more thing that struck me about plugins. We have a potential nightmare with versioning docs. There are two version numbers we can work against, the Forrest one and the plugin one. The idea is that plugins can be release independently of Forrest. So we could have Forrest 0.7 with OK for versions 0.1, 0.2 and 0.3 of plugin X, whilst 0.4 will only work in Forrest 0.8. Do we want to worry about maintaining docs for each version of the plugin as well? For example f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.1 f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.2 f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.3 f.o.a/0.8/docs/plugins/o.a.f.p.PLUGINNAME/0.4 Note that in this case, if 0.4 of the plugin works in 0.7 of Forrest we should also have the 0.4 plugin docs in the 0.7 branch. This starts to get horribly complicated. Ross
Re: problem with docs at forrest.apache.org/docs/dev/
Ross Gardler wrote: David Crossley wrote: Ross Gardler wrote: How do people suggest I integrate the plugin docs with the main website docs? If they went under docs/plugins/$plugin-name/ then they will fit better with the versioning system described above. OK, that's where I'll put them then. I assume we want to SVN them into place in the way I've prototyped (see commit above), rather than duplicate the xdocs in the docs-author site. It would be nice to have the docs available locally too, but that sounds hard to achieve. So yes, do what you said. Note, that the point to link into these docs will therefore be docs/plugins/index.html. That page will contain a link to all the individual plugin documents. One more thing that struck me about plugins. We have a potential nightmare with versioning docs. There are two version numbers we can work against, the Forrest one and the plugin one. The idea is that plugins can be release independently of Forrest. So we could have Forrest 0.7 with OK for versions 0.1, 0.2 and 0.3 of plugin X, whilst 0.4 will only work in Forrest 0.8. Do we want to worry about maintaining docs for each version of the plugin as well? For example f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.1 f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.2 f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.3 f.o.a/0.8/docs/plugins/o.a.f.p.PLUGINNAME/0.4 Note that in this case, if 0.4 of the plugin works in 0.7 of Forrest we should also have the 0.4 plugin docs in the 0.7 branch. This starts to get horribly complicated. Erk, the same horrid thought ocurred to me. I hope that we can get away with just having one set of docs for each major version. Let us start with that and change it later if we need to. As i say that, it sounds very unsatisfactory ... i don't know what to do. --David
Re: problem with docs at forrest.apache.org/docs/dev/
Quoting David Crossley [EMAIL PROTECTED]: Ross Gardler wrote: David Crossley wrote: Ross Gardler wrote: How do people suggest I integrate the plugin docs with the main website docs? If they went under docs/plugins/$plugin-name/ then they will fit better with the versioning system described above. OK, that's where I'll put them then. I assume we want to SVN them into place in the way I've prototyped (see commit above), rather than duplicate the xdocs in the docs-author site. It would be nice to have the docs available locally too, but that sounds hard to achieve. So yes, do what you said. Note, that the point to link into these docs will therefore be docs/plugins/index.html. That page will contain a link to all the individual plugin documents. One more thing that struck me about plugins. We have a potential nightmare with versioning docs. There are two version numbers we can work against, the Forrest one and the plugin one. The idea is that plugins can be release independently of Forrest. So we could have Forrest 0.7 with OK for versions 0.1, 0.2 and 0.3 of plugin X, whilst 0.4 will only work in Forrest 0.8. Do we want to worry about maintaining docs for each version of the plugin as well? For example f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.1 f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.2 f.o.a/0.7/docs/plugins/o.a.f.p.PLUGINNAME/0.3 f.o.a/0.8/docs/plugins/o.a.f.p.PLUGINNAME/0.4 Note that in this case, if 0.4 of the plugin works in 0.7 of Forrest we should also have the 0.4 plugin docs in the 0.7 branch. This starts to get horribly complicated. Erk, the same horrid thought ocurred to me. I hope that we can get away with just having one set of docs for each major version. Let us start with that and change it later if we need to. As i say that, it sounds very unsatisfactory ... i don't know what to do. Yes, lets try to keep it simple for now: release the plugins with each major version. When that becomes insufficient (e.g. if a plugin takes off and makes its own major changes releases within one forrest release), we can tackle it again. I think in that case, the plugin should be documented seperately from the main forrest docs and it can say what versions of forrest it is compatible with. -- Dave Brondsema : [EMAIL PROTECTED] http://www.brondsema.net : personal http://www.splike.com : programming http://csx.calvin.edu : student org
Re: problem with docs at forrest.apache.org/docs/dev/
On Tue, 2005-04-05 at 12:01 -0400, Dave Brondsema wrote: Quoting David Crossley [EMAIL PROTECTED]: Ross Gardler wrote: David Crossley wrote: Ross Gardler wrote: Note that in this case, if 0.4 of the plugin works in 0.7 of Forrest we should also have the 0.4 plugin docs in the 0.7 branch. This starts to get horribly complicated. Erk, the same horrid thought ocurred to me. I hope that we can get away with just having one set of docs for each major version. Let us start with that and change it later if we need to. As i say that, it sounds very unsatisfactory ... i don't know what to do. Yes, lets try to keep it simple for now: release the plugins with each major version. When that becomes insufficient (e.g. if a plugin takes off and makes its own major changes releases within one forrest release), we can tackle it again. I think in that case, the plugin should be documented seperately from the main forrest docs and it can say what versions of forrest it is compatible with. +1 Just a thought but doing a 'ant deploy' is a release for a plugin, isn't it? salu2 -- thorsten Together we stand, divided we fall! Hey you (Pink Floyd)
Re: problem with docs at forrest.apache.org/docs/dev/
David Crossley wrote: David Crossley wrote: David Crossley wrote: David Crossley wrote: Dave Brondsema wrote: /docs/dev/ nested below /docs/ seems weird. I think it would be better to host the current stable release at a url like: /docs/0.7/. This would also permit us to keep documentation for all old releases (although we would probably want warnings on them if they are too old). 0.6 docs had to be kept at /docs/ because they didn't have a split docs/site structure so I kept it as-is. I had been thinking we'd move to something like /docs/0.7/ for future releases, but I can't find any discussion about this in particular. We probably jumped to the conclusion that we only would have the current release and the current dev version. I agree with this new approach. So would it be like this ... Assuming that we don't want to version the top-level docs. Is that a legitimate assumption? It would change our layout if we do. I don't know the answer yet either. f.a.o/ ... the top-level docs, from trunk/site-author f.a.o/docs/ ... is .htaccess to redirect to current release docs. f.a.o/docs/0.6/ ... from the forrest_06_branch (*) f.a.o/docs/0.7/ ... from the forrest_07_branch, when it is released f.a.o/docs/0.8/ ... the next development, from future trunk/docs-author/ Let us see what the other solution would be. (Say that current release is 0.7) f.a.o/ ... the top-level docs, .htaccess to redirect to 0.7 top-level f.a.o/docs/ ... .htaccess to redirect to 0.7/docs/ f.a.o/0.6/ ... from the forrest_06_branch f.a.o/0.6/docs/ ... from the forrest_06_branch f.a.o/0.7/ ... from the forrest_07_branch/site-author/ f.a.o/0.7/docs/ ... from the forrest_07_branch/docs-author/ f.a.o/0.8/ ... the next development, from the trunk/site-author/ f.a.o/0.8/docs/ ... from the trunk/docs-author/ I have done local tests with both methods. The second way seems much easier and leaves more scope for the future. To use the first way, would also mean a re-structure of the docs part of forrest_06_branch. --David Furthering this idea, if we are versioning and storing docs-author and site-author, do we really need to store them seperately? As you said, this method would mean we won't have to restructure the forrest_06_branch docs into two parts. -- Dave Brondsema : [EMAIL PROTECTED] http://www.splike.com : programming http://csx.calvin.edu : student org http://www.brondsema.net : personal signature.asc Description: OpenPGP digital signature
Re: problem with docs at forrest.apache.org/docs/dev/
David Crossley wrote: Dave Brondsema wrote: /docs/dev/ nested below /docs/ seems weird. I think it would be better to host the current stable release at a url like: /docs/0.7/. This would also permit us to keep documentation for all old releases (although we would probably want warnings on them if they are too old). 0.6 docs had to be kept at /docs/ because they didn't have a split docs/site structure so I kept it as-is. I had been thinking we'd move to something like /docs/0.7/ for future releases, but I can't find any discussion about this in particular. We probably jumped to the conclusion that we only would have the current release and the current dev version. I agree with this new approach. So would it be like this ... Assuming that we don't want to version the top-level docs. Is that a legitimate assumption? It would change our layout if we do. I don't know the answer yet either. f.a.o/ ... the top-level docs, from trunk/site-author f.a.o/docs/ ... is .htaccess to redirect to current release docs. f.a.o/docs/0.6/ ... from the forrest_06_branch (*) f.a.o/docs/0.7/ ... from the forrest_07_branch, when it is released f.a.o/docs/0.8/ ... the next development, from future trunk/docs-author/ Actually we should be able to establish this prior to the 0.7 release. [*] the 0.6 stuff will have some inconsistencies, which we can fix in its branch, such as faq.html was one level up. The missing piece is that we need to clearly denote the version number on all docs. We should be able to do something rough-and-ready to get us by. That is fixed now. We can put a panel on the page and text after the html tile. --David
Re: problem with docs at forrest.apache.org/docs/dev/
David Crossley wrote: The missing piece is that we need to clearly denote the version number on all docs. We should be able to do something rough-and-ready to get us by. I have been experimenting with ways to do this. Even if just a quick fix, it needs to be configurable. I am calling this functionality Message Of The Day. Supposedly this can happen better at a later stage when we have the upcoming fbits and nuggets functionality IIUC. This is what i have done so far (not yet committed) ... In skinconf.xml (and added to skinconfig-v06-3.dtd) motd-title= motd-page= motd-page-url= ... they provide snippets of text to add to the document. So in the Forrest project, docs-author/skinconf.xml motd-title=v0.7 motd-page=This is documentation for the current release v0.7 motd-page-url=/docs/ Where motd-title adds the small text string in brackets after the htmltitle e.g. This Title (v0.7) Where motd-page adds a longer text string in a panel on the face of the page, with the motd-page-url being the hyperlink More e.g. +-+ | This is documentation for the | | current release v0.7 (More ...) | +-+ The panel can be added underneath the navigation left-hand side-panel (the default) or at the whitespace section at the top of the page next to the table of contents. Here is a screenshot, which shows both alternative locations for the MOTD panel: http://imagebin.org/1935 Should i continue with this workaround? --David
Re: problem with docs at forrest.apache.org/docs/dev/
David Crossley wrote: Here is a screenshot, which shows both alternative locations for the MOTD panel: http://imagebin.org/1935 Should i continue with this workaround? It looks great, just wheat we need. Ross
Re: problem with docs at forrest.apache.org/docs/dev/
Ross Gardler wrote: David Crossley wrote: Just a quick note, gotta rush out now. Yes there was stacks of discussion on this topic, but its good to be sure that we all understand, and maybe there is a flaw. The docs that are currently at docs/dev/ are 0.7-dev They will move to /docs/ when the next release happens. Then /docs/dev/ will become 0.8-dev and 0.6 (i.e. current /docs/) goes offline. Yes, that's the problem, all the mail archive links will be broken (in the sense they will refer to a different document from that referred to when the question was answered). Okay i found some of the old discussion and made links at http://issues.cocoondev.org/browse/FOR-391 --David
Re: problem with docs at forrest.apache.org/docs/dev/
Ross Gardler wrote: David Crossley wrote: Just a quick note, gotta rush out now. Yes there was stacks of discussion on this topic, but its good to be sure that we all understand, and maybe there is a flaw. The docs that are currently at docs/dev/ are 0.7-dev They will move to /docs/ when the next release happens. Then /docs/dev/ will become 0.8-dev and 0.6 (i.e. current /docs/) goes offline. Yes, that's the problem, all the mail archive links will be broken (in the sense they will refer to a different document from that referred to when the question was answered). Ross /docs/dev/ nested below /docs/ seems weird. I think it would be better to host the current stable release at a url like: /docs/0.7/. This would also permit us to keep documentation for all old releases (although we would probably want warnings on them if they are too old). 0.6 docs had to be kept at /docs/ because they didn't have a split docs/site structure so I kept it as-is. I had been thinking we'd move to something like /docs/0.7/ for future releases, but I can't find any discussion about this in particular. We should give links to documentation using a stable release, not /docs/dev (unless of course the issues in question is new to the dev version). That will keep all of our archived links good. -- Dave Brondsema : [EMAIL PROTECTED] http://www.splike.com : programming http://csx.calvin.edu : student org http://www.brondsema.net : personal signature.asc Description: OpenPGP digital signature
problem with docs at forrest.apache.org/docs/dev/
I just realised a problem with our documentation. Most of us provide links to the website when answering questions. Often these links refer to the current dev docs which are given an URL of http://forrest.apache.org/docs/dev/ Now, when we release the dev version (in this case 0.7) we will presumably move the docs to http://forrest.apache.org/docs/0.7/ This will break all the links in the mail archives, well OK, it won't actually break them but the URL will no longer point to the document we intended. In some cases the dev version of the document will no longer be relevant to the release version (for example if we replace skins with forrest:views in 0.8). I propose that we always publish to the correct version number and generate the dev docs with a warning at the top of each page like this: warningThis is a draft document. It describes functionality that may only be present in the current development version of Apache Forrest./warning This is easily done with our skinning system, even easier (I believe) with forrest:views. Whilst I'm on this topic, what happens to old documentation for past versions. I hope we intend to keep them in the webspace in order to keep these mail archive links alive. I'm sure this was discussed but can't remember what was decided. Ross
Re: problem with docs at forrest.apache.org/docs/dev/
Just a quick note, gotta rush out now. Yes there was stacks of discussion on this topic, but its good to be sure that we all understand, and maybe there is a flaw. The docs that are currently at docs/dev/ are 0.7-dev They will move to /docs/ when the next release happens. Then /docs/dev/ will become 0.8-dev and 0.6 (i.e. current /docs/) goes offline. Someone should find the old discussion thread please. --David
