content/xdoc/overview.xml (133 lines of code) (raw):
<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<document>
<properties>
<title>Overview Of The Doxia Framework</title>
<author>Vincent Siveton</author>
<date>2009-03-02</date>
</properties>
<body>
<section name="Overview Of The Doxia Framework">
<p>
The following figure represents the main components of the Doxia Framework.
</p>
<p>
<img src="images/architecture.png" width="574" height="439" border="0" usemap="#Doxia_Framework" alt="Doxia Framework"/>
<map id="Doxia_Framework" name="Doxia_Framework">
<area shape="rect" coords="87,45,172,99" alt="Sink API"
href="http://maven.apache.org/doxia/doxia/doxia-sink-api/" />
<area shape="rect" coords="66,170,193,232" alt="Core"
href="http://maven.apache.org/doxia/doxia/doxia-core/" />
<area shape="rect" coords="26,361,69,403" alt="APT Module"
href="http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-apt/" />
<area shape="rect" coords="78,361,119,403" alt="XDoc Module"
href="http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-xdoc/" />
<area shape="rect" coords="130,361,172,404" alt="FML Module"
href="http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-fml/" />
<area shape="rect" coords="14,311,235,428" alt="Modules"
href="http://maven.apache.org/doxia/doxia/doxia-modules/" />
<area shape="rect" coords="0,0,260,438" alt="Doxia"
href="http://maven.apache.org/doxia/doxia/" />
<area shape="rect" coords="297,157,422,200" alt="Site Renderer"
href="http://maven.apache.org/doxia/doxia-sitetools/doxia-site-renderer/" />
<area shape="rect" coords="455,157,557,200" alt="Decoration Model"
href="http://maven.apache.org/doxia/doxia-sitetools/doxia-decoration-model/" />
<area shape="rect" coords="298,209,421,251" alt="Doc Renderer"
href="http://maven.apache.org/doxia/doxia-sitetools/doxia-doc-renderer/" />
<area shape="rect" coords="286,114,575,262" alt="Site Tools"
href="http://maven.apache.org/doxia/doxia-sitetools/" />
<area shape="rect" coords="304,362,403,404" alt="Converter"
href="http://maven.apache.org/doxia/doxia-tools/doxia-converter/" />
<area shape="rect" coords="424,362,517,404" alt="Linkcheck"
href="http://maven.apache.org/doxia/doxia-tools/doxia-linkcheck/" />
<area shape="rect" coords="285,310,537,426" alt="Tools"
href="http://maven.apache.org/doxia/doxia-tools/" />
</map>
</p>
<p>
<b>Note</b>: Just like Maven, Doxia uses
<a class="externalLink" href="https://codehaus-plexus.github.io/">Plexus</a> extensively.
</p>
<subsection name="Sink API">
<p>
The <i>Sink</i> interface is a generic markup language interface. It contains
several methods that encapsulate common text syntax. A start tag is denoted by
<i>xxxx()</i> method and a end of tag by <i>xxxx_()</i> method.
</p>
<p>
For instance, you could do things like:
</p>
<source>sink.paragraph();
sink.text( "my text" );
sink.paragraph_(); </source>
<p>
similar to this HTML markup:
</p>
<source><p>my text</p></source>
<p>To find out more about the Sink API, you could read the Javadoc
<a class="externalLink"
href="http://maven.apache.org/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html">here</a>.
</p>
</subsection>
<subsection name="Doxia Core">
<p>
The <i>Core</i> is the API to parse a source and populate it in a <i>Sink</i>
object. The <i>Parser</i> interface contains only one method:
</p>
<source>void parse( Reader source, Sink sink )
throws ParseException; </source>
<p>
The <i>ParseException</i> class has the responsibility to catch all parsing
exceptions. It provides an helper method, <i>getLineNumber()</i>, which helps to
find where an error occurred.
</p>
<p>
The <i>AbstractParser</i> class is an abstract implementation of the
<i>Parser</i>. It provides a macro mechanism to give dynamic functionalities for
the parsing. For more information on macros, read the <a
href="./macros/index.html">Doxia Macro Guide</a>.
</p>
<p>
Finally, the <i>SiteModule</i> interface is the last part of the puzzle. It
provides main definitions of a given Doxia module and it is used by the
<i>doxia-site-renderer</i> site tools.
</p>
</subsection>
<subsection name="Doxia Modules">
<p>
A Doxia module is an implementation of a given markup language like APT or Xdoc.
Each module should implement these interfaces:
</p>
<ul>
<li><i>Parser</i> interface, more specifically the <i>AbstractParser</i> class</li>
<li><i>SiteModule</i> interface</li>
</ul>
<p>
Several modules provide also a <i>Sink</i> implementation to handle a specific
output markup language.
</p>
<p>
For more information on modules, read the <a href="./modules/index.html">Doxia
Module Guide</a>.
</p>
</subsection>
<subsection name="Doxia Site Tools">
<p>
The <i>Site Tools</i> are a collection of tools to renderer an output. The main
tool used by Maven, specifically the
<a class="externalLink" href="http://maven.apache.org/plugins/maven-site-plugin/">Maven Site Plugin</a>,
is the <i>doxia-site-renderer</i> which renders in HTML any
documents written with supported markup syntax. It uses
<a class="externalLink" href="http://velocity.apache.org/">Velocity templates</a>
to customize the renderer and the <i>site-decoration-model</i> tool to decorate the
renderer.
This component describes the layout of the site defined in the <i>site.xml</i>
file.
</p>
<p>
The <i>doxia-doc-renderer</i> tool is used to renderer any document in another
document.
</p>
</subsection>
</section>
</body>
</document>