Apache Forrest WikiRenderer
 
   

ForrestProposal

PDF
PDF

Background

This is an evolving proposal to determine how to smoothly enable the Cocoon documentation to be built by Apache Forrest.

----

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

cocoon-docs.

----

Outline of requirements and issues

1. Forrest to assist with building Cocoon system documentation. RELATED LINKS

  1. Using Forrest
  2. HowToForrestTransition
  3. Lots of discussion on cocoon-docs in late-March 2003

----

2. Forrest to automatically (or by manual trigger) generate the website at xml.apache.org/cocoon/

DECISION

will do this.

----

3. 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

----

4. 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 READER COMMENTS

  1. (ds) I believe I have successfully adapted earlier work to transform Cocoon docs to doc-v11 (and other) dtds.
  2. (ds) I have submitted a first draft. Issues remain. Please help resolve. See

HowToForrestTransition

----

5. 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.

----

6. 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.

----

7. 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.

----

8. The documents that are published by Forrest need to be subsequently checked-in to the xml-site CVS.

DECISION

will do this. READER COMMENTS

  1. (ds) Do you mean the live site cvs? Why? I thought the whole point of Forrest automation was to remove this step?
  2. (dc) Yes because this is how all xml.apache.org sites need to currently do this.
  3. (dc) ToDo: See current

email discussionand gather the issues when it is finished.

  1. (bd) I think Forrestbot aims to automate this, see

this thread

  1. (jt) We have a bunch of Forrest sites updating every hour, visible at

http://forrestbot.cocoondev.org. Automatic or manually triggered update of xml-site/targets/* is possible, but not enabled by default. RELATED LINKS

  1. PATCH: small news update patch for cocoon gettogether

- provides overview of the current cumbersome process to update the Cocoon website.

----

9. Use a consistent version of Forrest during the transition phase.

DECISION

  • Forrest cvs head now has a cvs tag called "stable".

----

10. Decide which "tabs" to use. See

Apache Incubatorfor 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.

----

11. 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.

READER COMMENTS

  1. (dc) Authors should remain hidden, especially for general documents like the home page. Also many CVS mistakes have been made where a minor patch contributor is listed as an "author". Too easily abused. Also some pages still contain the author of another page which was used only as a template.
  2. (ds) This may be appropriate for core docs, but I think allowing authors to have their names on How-Tos will increase the incentive to contribute. See also

http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=102552672926362&w=2I personally like the idea of giving credit to those submitting revision patches. This helps users understand what has changed. See an example of this at: http://xml.apache.org/cocoon/howto/howto-paginator-transformer.html.

  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.
  2. (dc) The author of any "group effort" page could be "cocoon-dev".

----

12. The status documents (changes, todo) need to merge into status.xml

DECISION

  • done

READER COMMENTS

  1. discussion about

single status.xml versus separate files

----

13. 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.

----

14. 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.

----

15. 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.

READER COMMENTS

  1. (dc) How do we we mark them as deprecated?
  2. (dc) Or perhaps we just delete them and people need to use an old version of Cocoon if they need to still use the old document-v10 DTDs. This sounds better because if we keep the DTDs then that implies that we keep the stylesheets/sitemaps to go with them (yikes, management nightmare).

RELATED LINKS

  1. forrest-dev email:

PROPOSAL: DTD Versioning

----

16. 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.

----

17. Perhaps the navigation/organization of pages should be revisited at the same time.

PROPOSAL

  • Leave this until after transition.

READER COMMENTS

  1. (dc) Perhaps this would make the job too big and so may delay it.
  2. (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.

----

18. Staging mechanism for quality control of website production

PROPOSAL

  • Leave this issue until after transition is finished. Forrestbot already addresses part of this need.

RELATED LINKS

  1. cocoon-dev email:

staging/promotion

  1. forrest-dev email:

RT: Site versioning, staging and deployment(Careful: There are followups with slightly different thread names.)

  1. cocoon-docs email:

Staging mechanism

----

19. From which branch does the website get generated - head or release branch?

PROPOSAL

  • Open

READER COMMENTS

  1. (dc) It is currently generated from the release branch. Those xdocs are meant to be always in sync with the head of CVS. The documentation does describe the head of CVS and we do not maintain any separate "release" version of the docs (rather we put notes in the documentation to indicate which branch applies). So why do we not generate the website from the head of CVS? The only reason that i can think of is that the "changes.html" on the website describes the current release branch and not all relevant changes to head have gone into release branch, so the "changes" documents are necessarily different.

RELATED LINKS

  1. cocoon-docs email:

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

- which came to the decision to try this Wiki

- the vote was considered premature (need proposal first)

----

To Do

  • Extract some more requirements and issues from

Nikola Ken summary

  • Fine-tune and prioritise this list of issues, then develop the actual proposal (see

email).

----

See also

Abbreviated names of readers

For readability's sake:

  • bd is

Bertrand Delacretaz

  • dc is

David Crossley

  • ds is

Diana Shannon

  • jt is Jeff Turner