David Crossley wrote:
Upayavira wrote:
David Crossley wrote:
The docs aspect needs lots of consideration. If Cocoon wants to continue using Forrest, then we would like help to implement our plans for the Forrestbot and staging server for reviewing docs prior to publication.
We had a huge discussion on this at infrastructure.at.a.o a few months ago. That needs to be summarised and brought into the open.
I think this is the sort of thing I was referring to. If we can clarify what we have in mind, and get a number of us behind it, then I could see it as being possible.
But there's a lot to clarify/understand. Would you be willing to explain here what you had in mind for your Forrestbot setup? Presumably this setup would still use CVS/SVN as the versioning system for the actual xdoc files?
Yes it does.
Well i will try. It is a big task. Did anyone see the infrastructure@ discussion to which i refer. It was not just about "forrestbot", rather the whole situation of publishing of documentation at Apache. There are so many aspects: oversight of content, staging, workflow, recoverability, quick turnaround, secure access, Forrestbot, Lenya, Doco, ...
The thread finished with the feeling that we had solutions, just in need of implementation.
Anyway, going off to dig through mail archives again ...
... back to the surface.
I have summarised that previous discussion from [EMAIL PROTECTED] and built two proposal documents. These are at the Forrest website.
Draft: Proposal for ASF-wide documentation staging and publishing http://forrest.apache.org/proposal-asf-publish.html This draws together various past discussions to address the diverse issues with documentation publishing at apache.org
With respect to the following "scratch note" in the above document:
Noel: We need to accommodate sites that come from a single source, and sites that come from multiple sources, e.g. Jakarta or the XML Federation.
A recent plugin for Forrest allows sites to use an IMS Manifest to define their structure, one of the main advantages of using this method over the existing method (which remains the default method) is that it allows a site to include other sites within their own site. That is, each subproject in Jakarta/XML would maintain their site independently of the main Jakarta/XML site. These "sub-sites" can be built independently of the main Jakarta/XML site for local testing purposes.
How will this impact the building process described in the above document?
Stages A through G will be unaffected. Each individual site would have its own staging area, hence there is no need to build the whole Jakarta or XML site in order to review minor changes in one of the sub sites. The main site can also be staged in the way described in the document.
Actions in stages H and I would depend on how the main site was built and the changes that have been made.
If the main site simply links to the subsites (as is currently the case) then this site will only need to be rebuilt when such a link is updated, or the contents of the main site are updated.
However, using this new plugin it is possible to have the menus for the sub-sites appear as collapsible menus in the main site. In this case the main site will need to be rebuilt whenever the structure of a subsite changes (i.e. a new page is added).
If changes to subsites are minor (text changes in a page for example), then only the sub-site need be published.
CAVEAT: This forrest plugin is currently in alpha. It is not even in SVN yet (pending a restructure of SVN to accommodate the new plugin functionality of Forrest). As author of the plugin I can assure you that I will assist in any changes required to meet the requirements of the ASF (I need similar functionality in the project this came from anyway).
Ross
