I am also for (2) although I can't promis much help. I think moving the docs to a CMS was one of the big mis-decisions of C2. The wishful thinking was that non-developers would come forward to improve the documentation which were before discouraged by the xdoc and svn. Sad reality was that the CMS created an extra threshold for any documentation update that it almost completely stopped.
We should come back to where code and doc changes can be committed and published together. One major improvement over the past scheme would be if doc changes could be previewed live without a build cycle. Cheers, Alfred. -----Original Message----- From: Francesco Chicchiriccò [mailto:ilgro...@apache.org] Sent: Freitag, 16. März 2012 10:46 To: dev@cocoon.apache.org Subject: Website management [WAS Re: resurrect the Cocoon documentation] Hi all, yesterday, while looking at cocoon.zones.apache.org, I've spent some time at our website, and the e-mail below came into my mind. I believe we should act in this respect as soon as possible, since our outdated website is all but attractive and informative: think only that every page reports "Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required)." pointing to a non-existing Daisy instance. Taking the attached e-mail into account, I think we should choose whether: 1. try to resurrect a Daisy instance in our jail - with Betrand's help / manage somehow 2.1 docs with forrest; 2. use Cocoon to parse existing HTML files (for C2.2 and C2.1) and generate a bunch of xdoc/apt files that will serve as a basis for managing a whole maven / svnsubpub based website (like as we're currently doing for C3); 3. use Apache CMS and try to import all existing documentation (including C3's, in this case) - as suggested by David in the e-mail below; I am for (2) and can spend some time for this, with some other volunteer, of course ;-) WDYT? Regards. On 16/01/2012 14:21, David Crossley wrote: > TL;DNR > Use the Apache CMS for at least our top-level docs > and the stalled 2.1 and 2.2 docs. > > > However, i cannot actually do this work, just explain and guide. > > I have done some background research to try to gather the > various past threads and docs. Perhaps this will help us to > bring the Cocoon documentation back to life. > > In the past we had the sources for the docs in xml format > and then processed by Apache Forrest to generate the html pages. > > A few years ago we moved to using the Daisy CMS to store/edit > all content for 2.1 and 2.2 versions, as well as the top-level > project non-version-specific stuff. > > For Cocoon-2.2, and the top-level stuff, the Maven site plugin > extracted the content from Daisy and generated the html pages. [4] > > For Cocoon-2.1, the Forrest plugin "Daisy input plugin" extracted > the content from Daisy and generated the html pages. [5] > > For Cocoon-3, the source content is stored in xml files > and the Maven site plugin generates the html pages. > > All generated html was (and still is) committed to the > Cocoon "site" SVN [1]. > > Then 'svn up' on the people.apache.org machine does the > publishing step. (Later that step could move to using svnpubsub.) > > The Daisy server operated on our Zones machine cocoon.zones.apache.org > (which also housed the demonstrations for Cocoon 2.1 and 2.2). > The Zones server is managed by the Cocoon project. See [2]. > > However, the machine that provided the zones for a set of > projects needed to be upgraded. The Cocoon project did not > move our services in time. > IIRC we do now have a "freebsd jail" which is basically configured, > but not yet re-installed Daisy or Cocoon demo examples, > nor the web server. > IIRC we did get a backup of the Daisy data [3] if that helps. > > The Forrest forrestbot neededi to be turned off, as it could not > access the source content for the 2.1 documentation. > > For the 2.2 documentation, i presume that Maven also has troubles. > > So unless someone can re-instate the new cocoon.zones.apache.org > and the Daisy server, then we need some other solution. > > Suggestion to use the Apache CMS: > > One other solution would be to use the new Apache CMS. [7] > > It can have source content in either Markdown format > or in HTML format and perhaps others. > > To resurrect the content, we might be able to use the > last published "generated" set of html documents, strip off > the outer headers and menu stuff, replace with basic header, > and use that set of content to seed the CMS. > > -------------------- > (Some of these resources are only available to Cocoon PMC members.) > > [1] http://svn.apache.org/repos/asf/cocoon/site/site/ > > [2] https://svn.apache.org/repos/private/pmc/cocoon/cocoon.zones.apache.org/ > > [3] Search the PMC archive for various email from Bertrand > > [4] http://cocoon.apache.org/1418_1_1.html > How to publish docs to cocoon.apache.org > (i.e. for Cocoon-2.2 and the top-level of c.a.o) > > [5] http://wiki.apache.org/cocoon/CocoonWebsiteUpdate > How to publish Cocoon-2.1 docs > > [7] Apache CMS > http://wiki.apache.org/general/ApacheCms2010 > http://wiki.apache.org/general/ApacheCMSFAQ > http://www.apache.org/dev/cmsref.html -- Francesco Chicchiriccò Apache Cocoon PMC and Apache Syncope PPMC Member http://people.apache.org/~ilgrosso/ The content of this e-mail is intended only for the confidential use of the person addressed. If you are not the intended recipient, please notify the sender and delete this email immediately. Thank you.
