It is recommended that you use Plexus to look up the parser. In principle you could instantiate the parser directly ( Parser parser = new AptParser(); ) but then some special features like macros will not be available.

What kind of attributes are supported depends on the event and the sink implementation. The sink API specifies a list of suggested attribute names that sinks are expected to recognize, and parsers are expected to use preferably when emitting events.

In Doxia 1.0 it was a common practice to use sink.rawText() to generate elements that were not supported by the Sink API. For example, the following snippet could be used to generate a styled HTML <div> block:

This has a major drawback however: it only works if the receiving Sink is a HTML Sink. In other words, the above method will not work for target documents in any other format than HTML (think of the FO Sink to generate a pdf, or a LaTeX sink,...).

In Doxia 1.1 a new method unknown() was added to the Sink API that can be used to emit an arbitrary event without making special assumptions about the receiving Sink. Depending on the parameters, a Sink may decide whether or not to process the event, emit it as raw text, as a comment, log it, etc.

Read the javadocs of the unknown() method in the Sink interface and the XhtmlbaseSink for information on the method parameters. Note that an arbitrary sink may be expected to ignore the unknown event completely!

In general, the rawText method should be avoided alltogether when emitting events into an arbitrary Sink.