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