doxia-sink-api/src/site/apt/index.apt

 -----
 Doxia Sink API
 -----
 Hervé Boutemy
 -----
 2010-05-08
 -----

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

Doxia Sink API

  The <Sink> interface is a generic markup language interface provided as a Java API.
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 can read the
  {{{./apidocs/org/apache/maven/doxia/sink/Sink.html}Javadoc}}.


* API Changes

  With every Doxia release, a new <<<doxia-sink-api>>> artifact has been released even if the API itself didn't change.

  Here is a summary of API changes:

*--------------+--------------------------+
|| <<doxia-sink-api version>> || <<change description>> ||
*--------------+--------------------------+
| 1.0-alpha-6  | added <<<org.apache.maven.doxia.sink.Sink>>> interface which supercedes <<<org.codehaus.doxia.sink.Sink>>> |
*--------------+--------------------------+
| 1.0-alpha-9  | added <<<org.apache.maven.doxia.sink.SinkFactory>>> interface |
*--------------+--------------------------+
| 1.1          | added <<<org.apache.maven.doxia.sink.SinkEventAttributes>>> interface and a dependency on <<<doxia-logging-api>>> |
*--------------+--------------------------+

  Note that <<<doxia-sink-api 1.0>>> is equivalent to <<<doxia-sink-api 1.0-alpha-9>>>.

* Maven dependency

  <<<doxia-sink-api>>> is included in every Maven 2 distribution. Decoupling has been done in Maven 3.

*--------------------+------------------------------+
|| <<Maven version>> || <<doxia-sink-api version>>  ||
*--------------------+------------------------------+
|        2.0.x       |            1.0               |
*--------------------+------------------------------+
|        2.1.x+      |            1.1               |
*--------------------+------------------------------+
|        3.0+        | <no more dependency>         |
*--------------------+------------------------------+

  Maven 2.0.8 is the first Maven 2.0.x version including <<<doxia-sink-api 1.0(-alpha-9)>>>.

  To hide the difference between <<<doxia-sink-api 1.0-alpha-6>>> and <<<1.0>>> included in previous Maven 2.0.x versions,
  <<<org.apache.maven.doxia.sink.SinkFactory>>> interface was copied into <<<maven-site-plugin 2.0-beta-6>>>.