-----
 Overview Of The Doxia Framework
 -----
 Vincent Siveton
 ------
 July 2007
 ------

~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Overview Of The Doxia Framework

 The following figure represents the main components of the Doxia Framework.

[images/architecture.png] Doxia Framework

 <<Note>>: Just like Maven, Doxia uses {{{http://plexus.codehaus.org/}Plexus}} extensively.

*Sink API

 The <Sink> interface is a generic markup language interface. It contains several methods that
 encapsulate common text syntax. A start tag is denoted by <xxxx()> method
 and a end of tag by <xxxx_()> method.

 For instance, you could do things like:

-----
 sink.paragraph();
 sink.text( "my text" );
 sink.paragraph_();
-----

 similar to this HTML markup:

-----
<p>my text</p>
-----

 To find out more about the Sink API, you could read the Javadoc
 {{{http://maven.apache.org/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html}here}}.

*Doxia Core

 The <Core> is the API to parse a source and populate it in a <Sink> object. The <Parser> interface
 contains only one method:

-----
void parse( Reader source, Sink sink )
    throws ParseException;
-----

 The <ParseException> class has the responsibility to catch all parsing exceptions. It provides an
 helper method, <getLineNumber()>, which helps to find where an error occurred.

 The <AbstractParser> class is an abstract implementation of the <Parser>. It provides a macro mechanism
 to give dynamic functionalities for the parsing. For more information on macros, read the
 {{{./macros/index.html}Doxia Macro Guide}}.

 Finally, the <SiteModule> interface is the last part of the puzzle. It provides main definitions of a
 given Doxia module and it is used by the <doxia-site-renderer> site tools.

*Doxia Modules

 A Doxia module is an implementation of a given markup language like APT or Xdoc. Each module should
 implement these interfaces:

  * <Parser> interface, more specifically the <AbstractParser> class

  * <SiteModule> interface

  []

 Several modules provide also a <Sink> implementation to handle a specific markup language.

 For more information on modules, read the {{{./modules/index.html}Doxia Module Guide}}.

*Doxia Sitetools

 The <Sitetools> are a collection of tools to renderer an output. The main tool used by Maven,
 specifically the {{{http://maven.apache.org/plugins/maven-site-plugin/}Maven Site Plugin}}, is the
 <doxia-site-renderer> which renders in HTML any documents wrote with supported markup syntax. It used
 {{{http://velocity.apache.org/}Velocity templates}} to customize the renderer and the
 <site-decoration-model> tool to decorate the renderer. This component describes the layout of the site
 defined in the <site.xml> file.

 The <doxia-doc-renderer> tool is used to renderer any document in another document.