Return-Path: Delivered-To: apmail-xml-cocoon-cvs-archive@xml.apache.org Received: (qmail 86781 invoked by uid 500); 13 Nov 2001 05:03:02 -0000 Mailing-List: contact cocoon-cvs-help@xml.apache.org; run by ezmlm Precedence: bulk Reply-To: cocoon-dev@xml.apache.org list-help: list-unsubscribe: list-post: Delivered-To: mailing list cocoon-cvs@xml.apache.org Received: (qmail 86769 invoked by uid 500); 13 Nov 2001 05:03:02 -0000 Delivered-To: apmail-xml-cocoon2-cvs@apache.org Date: 13 Nov 2001 04:50:11 -0000 Message-ID: <20011113045011.27412.qmail@icarus.apache.org> From: crossley@apache.org To: xml-cocoon2-cvs@apache.org Subject: cvs commit: xml-cocoon2/documentation/xdocs/plan book.xml index.xml catalog.xml doc.xml to-avalon.xml X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N crossley 01/11/12 20:50:11 Added: documentation/xdocs/plan book.xml index.xml catalog.xml doc.xml to-avalon.xml Log: Initial documentation for planning notes. Revision Changes Path 1.1 xml-cocoon2/documentation/xdocs/plan/book.xml Index: book.xml =================================================================== 1.1 xml-cocoon2/documentation/xdocs/plan/index.xml Index: index.xml ===================================================================
Planning Documentation Overview

This is a collection of notes to assist with long-term planning and development.

There is much discussion of issues and research topics (RT) threads on the cocoon-dev mailing list (and elsewhere). However, details get lost in the sheer volume. This is the place to document the summary of discussions on some key topics. Some new and complex capabilities will take lots of design and specification before they can be implemented.

Another use for this collection of notes is as a place to quickly store a snippet from an email discussion or even a link to a discussion thread. The concepts can then be fleshed-out over time.

Anyone can participate in this process. Please get involved in discussion on cocoon-dev and contribute patches for these summary planning documents via the normal contribution process.

These planning documents are intended to be concise notes only. They are also ever-evolving, because as issues are addressed these notes will be revised.

  • Moving some Components to Avalon
  • Documentation - revisions and additions are required
  • Entity Catalogs - the entity resolver
  • See the general To Do list and the cocoon-dev email archives for other issues
 1.1 xml-cocoon2/documentation/xdocs/plan/catalog.xml Index: catalog.xml ===================================================================
Entity Catalogs - the Entity Resolver Planning Documentation

The entity resolution capability is recently implemented at the Cocoon level. However, this capability is required for all XML Apache projects. So its base implementation should be moved to Avalon Excalibur.

Everytime that an XML parser is used, it needs to have the resolver attached via the setEntityResolver() method.

Cocoon and other projects need to be able to configure the resolver to specify additional catalogs and to set the verbosity level for the log messages.

For background see the main Cocoon documentation for Entity Catalogs.

TODO: describe overview of issues.

cocoon-dev 2001-11-09 (Identifying Components for Avalon) ... It would be reasonable for there to be an ExcaliburResolver, and a CocoonResolver that both extend the same interface. In fact, it would be reasonable for the CocoonResolver to extend the ExcaliburResolver.

1.1 xml-cocoon2/documentation/xdocs/plan/doc.xml Index: doc.xml ===================================================================
Documentation revisions and additions Overview

Of course, the Cocoon documentation is always undergoing evolution. These notes remind us of some things that have been discussed and not yet implemented.

The following sections list some documents that need revision and some required additional documents. At the bottom is a list of general issues.

  • Announcement (announcement.xml)
    • Needs to be more positive
    • Needs a concise overview of Cocoon (which can be re-used on the home page)
  • The home page (index.xml)
    • needs to be more positive
    • Can now stop apologising for Cocoon 1
    • Needs concise overiew at top - "What is It"
  • Frequently Asked Questions
    • Needs re-structure or we will have the same un-wieldy monster FAQ as for Cocoon 1.
  • Index pages for "Developing" and "Userdocs"
    • These pages have a shell, but no content yet.
    • They currently have the embarrassing "Under Construction" type of notice.

Certain issues need to be addressed for all current and future documentation.

  • Many pages use source elements to list code or configuration information. Wide pre-formatted text lines do not word-wrap in HTML output and so the user would need to painfully scroll left-and-right to read the page.
  • All documentation needs to be continually revised. It cannot be written and then never updated. It needs to keep in step with the code and configuration changes.
1.1 xml-cocoon2/documentation/xdocs/plan/to-avalon.xml Index: to-avalon.xml ===================================================================
Moving some Components to Avalon Overview

Certain appropriate components need to move to Avalon. The aim of these planning documents is to identify which components and any key requirements. These issues would then be discussed together with the Avalon team - some may need to be re-designed. After the components are moved to Avalon, then we need to re-integrate those components back into Cocoon.

List of interfaces:

  • XMLConsumer
  • XMLizable
  • XMLFragment
  • Parser
  • XMLSerializer/XMLDeserializer
  • XSLTProcessor

Everything dealing with Source objects. (This is the part which needs redesign to fit into Avalon!)

  • SourceResolver
  • SourceHandler
  • SourceFactory
  • Source
  • ModifiableSource

List of Implementations:

  • AbstractXMLConsumer
  • JaxpParser, XercesParser
  • XMLByteStreamCompiler/XMLByteStreamInterpreter
  • Everything dealing with Source objects
  • XSLTProcessorImpl
  • Entity Catalogs - the entity resolver
 ---------------------------------------------------------------------- In case of troubles, e-mail: webmaster@xml.apache.org To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org For additional commands, e-mail: cocoon-cvs-help@xml.apache.org