Date: 2004-12-04T17:18:23 Editor: DavidCrossley <[EMAIL PROTECTED]> Wiki: Cocoon Wiki Page: ForrestProposal URL: http://wiki.apache.org/cocoon/ForrestProposal
this document is still very relevant Change Log: ------------------------------------------------------------------------------ @@ -1,36 +1,34 @@ -'''''Note:''''' Some parts of this document are not relevant anymore since Cocoon has its docs built by Forrest. The problem areas are now the generation of the docs via the webapp. +#pragma section-numbers off + +'''''Note:''''' Some parts of this document are not relevant anymore since Cocoon now has its docs built by Forrest. The problem areas are now the generation of the docs via the webapp. == Background == -This is an evolving proposal to determine how to smoothly enable the Cocoon documentation to be built by [http://xml.apache.org/forrest/ Apache Forrest]. +This is an evolving proposal to determine how to smoothly enable the Cocoon documentation to be built by [http://forrest.apache.org/ Apache Forrest]. The main issue is that the Cocoon xdocs are still in an old xdocs format and Cocoon still uses very old stylesheets to process those documents when running Cocoon as a webapp. ----- == Procedure == Let us start by determining the dot-points in the "Outline" section below, to express requirements and issues. * Please keep the dot-point numbers, just add new ones at the bottom. In this way we can just refer to item numbers during email discussion. * Please add your comments or relevant links below any item. - * If you want to make major changes then please be sure to discuss that on [http://xml.apache.org/cocoon/mail-lists.html cocoon-docs]. + * If you want to make major changes then please be sure to discuss that on [http://cocoon.apache.org/community/mail-lists.html cocoon-dev]. ----- == Outline of requirements and issues == === Forrest to assist with building Cocoon system documentation. === RELATED LINKS - 1.[http://xml.apache.org/forrest/your-project.html Using Forrest] + 1.[http://forrest.apache.org/docs/your-project.html Using Forrest] 1.HowToForrestTransition 1.Lots of discussion on cocoon-docs in late-March 2003 ----- -=== Forrest to automatically (or by manual trigger) generate the website at xml.apache.org/cocoon/ === +=== Forrest to automatically (or by manual trigger) generate the website at cocoon.apache.org/ === DECISION - * [http://forrestbot.cocoondev.org Forrestbot] will do this. + * [http://forrest.apache.org/ Forrestbot] will do this. + * See also the [http://forrest.apache.org/proposal-asf-publish.html ASF publishing proposal] ----- === How will people who download just Cocoon, be able to locally build and work with its documentation? Do they need to install Forrest separately, or does Cocoon still build its own documentation using its own set of stylesheets? === PROPOSAL * open ----- === Cocoon xdocs need to be transformed to document-v11 DTD. Forrest has stylesheets, DTDs, anttasks, and XML validation to assist with this. === PROPOSAL * Follow HowToForrestTransition @@ -38,26 +36,22 @@ 1.(ds) I believe I have successfully adapted earlier work to transform Cocoon docs to doc-v11 (and other) dtds. 1.(ds) I have submitted a first draft. Issues remain. Please help resolve. See HowToForrestTransition ----- === After Cocoon xdocs are sucessfully transformed, the xdocs in CVS will be updated to be document-v11 type. === PROPOSAL * One person needs to update CVS when they are happy with the transition, then others can help to refine it. READER COMMENTS 1.(ds) And do we delete legacy dtds or simply remove any configuration (schema) reference to them? (dc) Added new item 15 below to deal with this. ----- === Simultaneously with #5, the Cocoon XSLT stylesheets, DTDs, and sitemaps will need to be updated to reflect the document-v11 from Forrest. === PROPOSAL * open READER COMMENTS 1.(ds) How will we synchronize this with Forrest updates? (dc) ? Not sure what you mean Diana. ----- === Expect a few people to help, especially during the transition of xdocs. === PROPOSAL * At some stage we are going to need to just break the docs/webapp-docs parts of cocoon-2.1 and this disruption will take a few people to put it back together. ----- === The documents that are published by Forrest need to be subsequently checked-in to the xml-site CVS. === DECISION * [http://forrestbot.cocoondev.org Forrestbot] will do this. @@ -70,19 +64,16 @@ RELATED LINKS 1. [http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=103408114414107 PATCH: small news update patch for cocoon gettogether] - provides overview of the current cumbersome process to update the Cocoon website. ----- === Use a consistent version of Forrest during the transition phase. === DECISION * Forrest cvs head now has a cvs tag called "stable". ----- === Decide which "tabs" to use. See [http://incubator.apache.org/ Apache Incubator] for one example of tab use. === DECISION * Use the tabs that are suggested below. These are easy to re-arrange. READER COMMENTS 1. (bd) I suggest "Home, Usage, Reference, Wiki, Links". "Usage" would include FAQs, tutorials and How-Tos, there is certainly a better name than "usage" for this. "Wiki" would be just one page with info on the wiki role and a link to it. ----- === Decide whether we want to show the "authors" of each document (which may not be relevant as it is a group effort). === PROPOSAL * Do not show the author of the home page. Show authors of all other pages. Review the <author> element of all xdocs. @@ -92,28 +83,24 @@ 1. (dc) I agree that contributors get recognition as shown with howto-paginator-transformer. However this is a different issue. The xml element document/header/author is what we are concerned about here. 1. (dc) The author of any "group effort" page could be "cocoon-dev". ----- === The status documents (changes, todo) need to merge into status.xml === DECISION * done READER COMMENTS 1. discussion about [http://marc.theaimsgroup.com/?l=forrest-dev&m=103757786405434 single status.xml versus separate files] ----- === Elevate doc-related changes and todo documents to top-level status file. === PROPOSAL * open READER COMMENTS 1. (ds) See status-docs.xml in transition trial run sample files. ----- === Need a mechanism to enable existing and future (with any reorganization) redirect pages. === PROPOSAL * open READER COMMENTS 1. (dc) I would rather leave this until after transition. ----- === Do the old documnet-v10 DTDs and OASIS Catalog entries need to remain in Cocoon CVS? Other people may be still using them for their own projects. === PROPOSAL * Follow whatever Forrest decides to do. @@ -123,14 +110,12 @@ RELATED LINKS 1. forrest-dev email: [http://marc.theaimsgroup.com/?l=forrest-dev&m=103984525624412 PROPOSAL: DTD Versioning] ----- === Decide if Cocoon needs its own skin (to protect its identity/brand) before/shortly after transition, given the fact many sites are adopting the default skin and given the prospect of top-level project status. === PROPOSAL * open READER COMMENTS 1. (dc) I would rather leave this until after transition. ----- === Perhaps the navigation/organization of pages should be revisited at the same time. === PROPOSAL * Leave this until after transition. @@ -138,7 +123,6 @@ 1. (dc) Perhaps this would make the job too big and so may delay it. 1. (ds) Transition first and reorganize later!! First, we don't even have an efficient redirect mechanism in place. Second, transitioning will save me tons of time (which I could then devote to other doc concerns) as I won't have to perform manual updates to the live site. ----- === Staging mechanism for quality control of website production === PROPOSAL * Leave this issue until after transition is finished. Forrestbot already addresses part of this need. @@ -147,7 +131,6 @@ 1.forrest-dev email: [http://marc.theaimsgroup.com/?l=forrest-dev&m=103649129528547 RT: Site versioning, staging and deployment] (Careful: There are followups with slightly different thread names.) 1.cocoon-docs email: [http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=103740900514863 Staging mechanism] ----- === From which branch does the website get generated - head or release branch? === PROPOSAL * Open @@ -156,27 +139,22 @@ RELATED LINKS 1. cocoon-docs email: [http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=104139048431290 Out of which branch should the website be published?] ----- === Recent major changes === * 2003-04-06 Noted some decisions and fine-tuned the text. ----- === Some relevant email discussion and documents === * [http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=103587005004773 PROPOSAL: Use Forrest to build Cocoon docs] - which came to the decision to try this Wiki * [http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=103575949409461 VOTE: Use Forrest to build Cocoon docs] - the vote was considered premature (need proposal first) * [http://marc.theaimsgroup.com/?l=forrest-dev&m=102456379811908 Cocoon docs transition report] ----- === To Do === * Extract some more requirements and issues from [http://marc.theaimsgroup.com/?l=forrest-dev&m=103649129528547 Nikola Ken summary] * Fine-tune and prioritise this list of issues, then develop the actual proposal (see [http://marc.theaimsgroup.com/?l=xml-cocoon-docs&m=103812701406163 email]). ----- == See also == * HowToForrestTransition ----- == Abbreviated names of readers == For readability's sake: * bd is BertrandDelacretaz
