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
===================================================================
<?xml version="1.0"?>
<book software="Apache Cocoon"
title="Apache Cocoon planning"
copyright="@year@ The Apache Software Foundation">
<menu label="Navigation">
<menu-item label="Main" href="../index.html"/>
</menu>
<menu label="Planning Documents">
<menu-item label="To Avalon" href="to-avalon.html"/>
<menu-item label="Documentation" href="doc.html"/>
<menu-item label="Entity Catalogs" href="catalog.html"/>
</menu>
</book>
1.1 xml-cocoon2/documentation/xdocs/plan/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../../dtd/document-v10.dtd">
<document>
<header>
<title>Planning Documentation</title>
<subtitle>Overview</subtitle>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>This is a collection of notes to assist with long-term planning and
development.
</p>
<p>There is much discussion of issues and research topics (RT) threads on
the <code>cocoon-dev</code> 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.
</p>
<p>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.
</p>
<p>Anyone can participate in this process. Please get involved in discussion
on <code>cocoon-dev</code> and contribute patches for these summary planning
documents via the normal <link href="../contrib.html">contribution</link>
process.
</p>
<p>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.
</p>
</s1>
<s1 title="Topics and Issues">
<ul>
<li><link href="to-avalon.html">Moving some Components to Avalon</link></li>
<li><link href="doc.html">Documentation</link>
- revisions and additions are required</li>
<li><link href="catalog.html">Entity Catalogs</link>
- the entity resolver</li>
<li>See the general <link href="../todo.html">To Do</link> list
and the <code>cocoon-dev</code> email archives for other issues</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/plan/catalog.xml
Index: catalog.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>Entity Catalogs - the Entity Resolver</title>
<subtitle>Planning Documentation</subtitle>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>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.
</p>
<p>Everytime that an XML parser is used, it needs to have the resolver
attached via the <code>setEntityResolver()</code> method.
</p>
<p>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.
</p>
<p>For background see the main Cocoon documentation for
<link href="../userdocs/concepts/catalog.html">Entity Catalogs</link>.
</p>
</s1>
<s1 title="Moving to Avalon">
<note>TODO: describe overview of issues.</note>
</s1>
<s1 title="Other Notes">
<p> 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.
</p>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/plan/doc.xml
Index: doc.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>Documentation revisions and additions</title>
<subtitle>Overview</subtitle>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>Of course, the Cocoon documentation is always undergoing evolution.
These notes remind us of some things that have been discussed and not
yet implemented.
</p>
<p>The following sections list some documents that need revision and some
required additional documents. At the bottom is a list of general issues.
</p>
</s1>
<s1 title="Revisions Required">
<ul>
<li>Announcement (announcement.xml)
<ul>
<li>Needs to be more positive</li>
<li>Needs a concise overview of Cocoon (which can be re-used on the home
page)</li>
</ul>
</li>
<li>The home page (index.xml)
<ul>
<li>needs to be more positive</li>
<li>Can now stop apologising for Cocoon 1</li>
<li>Needs concise overiew at top - "What is It"</li>
</ul>
</li>
<li>Frequently Asked Questions
<ul>
<li>Needs re-structure or we will have the same un-wieldy monster FAQ as
for Cocoon 1.
</li>
</ul>
</li>
</ul>
</s1>
<s1 title="Additional Documents Required">
<ul>
<li>Index pages for "Developing" and "Userdocs"
<ul>
<li>These pages have a shell, but no content yet.</li>
<li>They currently have the embarrassing "Under Construction"
type of notice.</li>
</ul>
</li>
<!--
<li>
<ul>
<li>
</li>
</ul>
</li>
-->
</ul>
</s1>
<s1 title="General Issues">
<p>Certain issues need to be addressed for all current and future
documentation.
</p>
<ul>
<li>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.
</li>
<li>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.
</li>
</ul>
</s1>
</body>
</document>
1.1 xml-cocoon2/documentation/xdocs/plan/to-avalon.xml
Index: to-avalon.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>Moving some Components to Avalon</title>
<subtitle>Overview</subtitle>
<authors>
<person name="Carsten Zeigeler" email="[EMAIL PROTECTED]"/>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>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.
</p>
<p>List of interfaces:</p>
<ul>
<li>XMLConsumer</li>
<li>XMLizable</li>
<li>XMLFragment</li>
<li>Parser</li>
<li>XMLSerializer/XMLDeserializer</li>
<li>XSLTProcessor</li>
</ul>
<p>Everything dealing with Source objects. (This is the part
which needs redesign to fit into Avalon!)
</p>
<ul>
<li>SourceResolver</li>
<li>SourceHandler</li>
<li>SourceFactory</li>
<li>Source</li>
<li>ModifiableSource</li>
</ul>
<p>List of Implementations:</p>
<ul>
<li>AbstractXMLConsumer</li>
<li>JaxpParser, XercesParser</li>
<li>XMLByteStreamCompiler/XMLByteStreamInterpreter</li>
<li>Everything dealing with Source objects</li>
<li>XSLTProcessorImpl</li>
<li><link href="catalog.html">Entity Catalogs </link>
- the entity resolver</li>
</ul>
</s1>
<s1 title="Other Notes">
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
