cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] Updated: ForrestProposal
Date Sun, 05 Dec 2004 01:18:23 GMT
   Date: 2004-12-04T17:18:23
   Editor: DavidCrossley <crossley@apache.org>
   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

Mime
View raw message